Commit messages

It's important to write good commit messages that will stand the test of time, so that those who review your patches can know what the patch is supposed to do, and so that anyone looking at the repository history (e.g. when tracking down a regression) can see what was done in the past.

General format

Commit messages in git repositories typically adhere to the following format:

Short one line description of commit, preferably <= 60 chars

This is line 3 where a long description of the commit can start. Line 2
above should always be left blank. The long description should normally
include some background on why this commit was required and why it is
best that the commit changes things the way it does. Lines should
preferably be <= 70 characters.

Commands

It's also possible to send commands to Trac in commits. Commit messages are searches for text in the form of:

command #1
command #1, #2
command #1 & #2
command #1 and #2

Instead of the short-hand syntax "#1", "ticket:1" can be used as well, e.g.:

command ticket:1
command ticket:1, ticket:2
command ticket:1 & ticket:2 
command ticket:1 and ticket:2

In addition, the ':' character can be omitted, and issue or bug can be used instead of ticket.

You can have more than one command in a message. The following commands are supported. There is more than one spelling for each command, to make this as user-friendly as possible.

close, closed, closes, fix, fixed, fixes

The specified tickets are closed, and the commit message is added to them as a comment.

references, refs, addresses, re, see

The specified tickets are left in their current status, and the commit message is added to them as a comment.

A fairly complicated example of what you can do is with a commit message of:

Changed blah and foo to do this or that.

Fixes #10 and #12, and refs #12.

This will close #10 and #12, and add a note to #12.

It is recommend to put all commands on line 3 and later in commit messages, even if line 1 is really short. That way, the commands will not be shown in single line formatting of commit messages, e.g. in gitweb or with git log --oneline.

When using the close command, the ticket owner will be set to the Author of the commit. Unfortunately there is no mapping between Trac usernames and name+email addresss as used in the Author field. The commands will be recorded as performed by the full Author email for the commit. We'll see how it goes, if it is a big problem an attempt may be made to fix this in Trac.