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 back at the repository history can see what was done.

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. The
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. Note that line 2
should be left blank.

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.