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:

One-line description of logical change, preferably <= 60 chars, absmax 72

This is line 3 where a longer 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 at all, if that
is not obvious from the change itself, and the description should also
mention why it is best that the commit changes things the way it does
instead of some other way. It's very good to summarize discussion leading
up to the change. Lines should preferably be <= 70 characters, absmax 75

Commands in libusb commits

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.