wiki:Development
Last modified 5 years ago Last modified on 09/23/11 13:05:07

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

You can send commands to Trac within commit messages, 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 and that.

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

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

When using a command to close a ticket, the ticket owner will be set to the Author of the commit. There is a mapping from the author's email address to the email address registered for the Trac account. If a match is found the Trac username is used. If no match is found then the full Author email in the commit is used.