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, mention the ticket number at the end of the body as meta data, e.g. Bug: 1234 . This will link the UI to the bugzilla ticket in question, and makes it indexable in Gerrit search (since it can only index key/value pairs on separate lines separated by colon)
 * 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

The first line is considered by Git to be the "Subject" of the commit. A typical use case is the Wikimedia Foundation creating their releases notes automatically (as seen on MediaWiki 1.21/wmf2), which emphasize the need of a meaningful and short summary for your commit. Bytes are cheap, so just write!

The full commit message should thus look like this:

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

Bug: 1234

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