Editing Issue Files¶
New in version 0.9: Editing of issue files.
There are some occasions when you might want to edit an issue file directly:
- To change an attribute that PyDitz doesn’t (yet) let you do with any other command (e.g., changing the issue type from a feature to a task).
- To clean up the issue text (e.g., correct speling mistakes).
You could, of course, just go into the issue directory and edit the issue file outside of PyDitz; nothing is stopping you. But as a convenience, there’s also an edit command. This has a couple of advantages:
- It saves you having to search for the correct issue file.
- After the edit, checks are done to make sure that you haven’t inadvertently produced an inconsistent or unreadable file.
Configuring the editor¶
In order to edit issue files, you need to tell PyDitz the editor you want to use. Here’s how one is found:
First, it checks the ‘editor’ setting in your Configuration File. If set, that is used.
Next, the environment variables
DITZEDITOR
,EDITOR
andVISUAL
are examined, in that order. If any is set, it’s used.Finally, if the operating system has a suitable default, that’s used. On Linux, that’s
vi
. On Windows, there is no default; you’ll have to explicitly specify an editor using one of the methods above.Warning
On Windows,
notepad
andwordpad
are not suitable editors. Instead, I recommend you get and use Notepad++.
Editing an issue¶
To edit an issue, you can either type pyditz
edit at a shell prompt,
or just edit at the Ditz:
prompt, specifying the issue you want to
edit. (From the Ditz:
prompt, if no issue is given, the last issue
mentioned in a command will be used.)
Your editor will be invoked on the raw issue text; this is in YAML format, and you can see an example in Database Internals. You should do your editing, save the current file, and exit. After that, one of several things will happen:
- If you didn’t make any changes, PyDitz will inform you of the fact and nothing will be done.
- If your edits produced an invalid file (either unreadable YAML or an invalid PyDitz issue format) you’ll be told what’s wrong and asked whether you want to re-edit the text to fix the problem. If you decide not to, the changes are abandoned.
- If your edits were accepted, the issue will be updated accordingly.