Login | Register
My pages Projects Community openCollabNet

Pre-Commit Script

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.

Pseudo-Headers

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 issue.

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.

An Example

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:

Subissue: /issues/assigned/your-username/issue-314159
Subissue-Status: Resolved
Subissue-Resolution: Fixed

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 repository.

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 <your@email.com>
Subissue-Status: Started

in the log message and automatically assign the issue to yourself.

Header Hooks

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/accepted/your-username/issue-314159 to /issues/resolved/issue-314159, for example.

Credits

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.