Subissue's pre-commit script integrates directly with the
Subversion commit process. When you commit a change to the
repository, the script analyzes your log message, looking for specific
keywords. These keywords specify how any issues related to your
commit should be updated.
The script looks for pseudo-headers in your log message, similar to
(and based on) the headers used in issue
descriptions and comments. Subissue first looks for a
"Subissue:" header, which specifies the path to the relevant
Once Subissue sees the "Subissue:" header, it looks for
other headers beginning with "Subissue-*:", and looks at the
part shown here as the "*". Subissue interprets that part as the name
of one of the headers in the issue's description, and replaces the
values of those headers in the description with the values specified
in the log.
So, say you have been working on the issue in
/issues/assigned/your-username/issue-314159/. You have
developed a fix which involves fixing the fubar in
baz.c, and in the process of committing the fix to the
repository, you want to mark the issue as "resolved". You would
compose your log message as follows:
Fixed the fubar in baz.c; the whatzit was messing up the hoozer.
When you commit this message, Subissue's pre-commit script sees the
"Subissue:" header, and opens the issue contained in
/issues/assigned/you/issue-314159 (which must have the
subissue:type set to directory, by the way). Then:
- It finds the file in that directory where subissue:type
is set to issue, and opens that file.
- Inside, it changes the Status header to "Resolved", and
the "Resolution" header to "Fixed".
- It creates a new file in that directory and sets
subissue:type to comment (the name of this new file
is configurable, and defaults to "comment-XXX", where "XXX"
is a number).
- Inside the new comment file, the Date and Author
headers are set as appropriate, and your original log message is
copied as the text of the comment.
- Finally1, the modified
description, the new comment, and your original changes are all
committed as one new revision, using your original log message (with
the "Subissue-*:" headers removed), as a new revision in the
Whew! It's not as complicated as it sounds. Really, this feature
extremely useful in day-to-day programming. By including additional
Subissue-* headers in the log message, you can modify or
create any header in the issue's description. For example, when you
create a new branch to work on an issue, you can include:
Subissue-Assigned-To: your-username <firstname.lastname@example.org>
in the log message and automatically assign the issue to
Actually, there is one more step that may happen in the course of
committing your changes. The pre-commit script allows you to specify
hooks that are executed whenever a specific
header is updated. See the Header Hooks page for more information.
In the first example above, Status: is changed from
"Started" to "Resolved". A hook could be configured to automatically
move the issue's directory from
/issues/resolved/issue-314159, for example.
Credit for the idea behind the pre-commit scripts and header
interpretation is due to Sergey A. Lipnevich
(remove SPAM protection), who suggested an XML-based version.