Gerrit/Commit message guidelines


 * Please note this article is also transcluded at Git/Workflow.

Commit message guidelines
Crafting the commit message is a very important step of your development work. The message is usually the first thing other developers will see, and the first line in a Git commit-msg has a special meaning. It is considered the "Title" or "Subject" of the commit. Many interfaces use this title to represent the commit, such as:
 * Subject of e-mail notifications
 * 's "oneline" mode
 * Gerrit interface (dashboard, search results, title)
 * Git revert (cites the commit title)
 * Various Git GUI clients (use first line as title until first empty line or end of body)

Aside from the tools that use it, it is also considered useful to the reviewer to have a concise headline identifying the commit. If you can't summarise your commit in a short line, perhaps it is still in a too early phase to submit or maybe it contains too many different things that should be broken up into different commits.

After the headline follows the body of the commit message. The body must be separated from the headline with an empty line. In here put a detailed message fully explaining your patch, what you did, your design choice, possible culprit to look at, any research you have done. Bytes are cheap, so just write! Generally the message body should wrap between 70-100 characters.

A few other guidelines for the content of the headline or the body:
 * If your change will resolve a ticket in bugzilla, put the ticket number at the very beginning of the headline in parentheses ( e.g ).
 * Whenever you refer to another commit, using either the git-commit SHA1 of the merged commit or the Gerrit Change-Id of the change set in Gerrit. Do not refer to git commit hashes of changes that have not been merged yet, in that case you should use the Gerrit Change-Id.

Good example :



Details
This section is not included in Git/Workflow

Since the first line is used by our Gerrit review tool to generate emails, that will make life easier to people receiving email notifications. Gerrit will also link the bug number automatically to the Bugzilla report. A typical use case is the Wikimedia Foundation creating their branch releases notes automatically, such as MediaWiki_1.21/wmf2, which highlight the need of a meaningful and short summary for your commit. The rest (what you did, the design choice, possible culprit to look at, any test you could have done), should land in the body of your message. Remember that people very often review code that they never even tried to run, so always provide relevant context and suggest ways to test the change. Bytes are cheap, so just write!

The full format should thus be:

(bug 1234) Summary line used as a subject usually

Rest of the message detailing your change, can be a long message if needed, for example to explain your design considerations.

Please split your paragraphs with new lines :-)

The rest is pretty much free form, you can even use ascii art since commit messages are usually displayed using a monospace font.

,         ,       /             \    ((__-^^-,-^^-__))     `-_---' `---_-'      `--|o` 'o|--' \ `  /          ): :(          :o_o: "-" ASCII Copyright (C) 2012, Free Software Foundation, Inc. Published under the GPL v2

Rendering example in the vim editor with syntax coloring:



Which, once pushed to Gerrit, will roughly look like:



And generate an IRC notification:



See also:
 * http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
 * Git/Introduction
 * http://datamapper.org/using-git.html