Summary

  1. The Subject should begin with the issue related to this commit (‘ARIA-XXXX’)

  2. Try to limit your subject to 50 characters, but definitely don’t go over 72

  3. Start the subject line (after the issue tag) with a capital letter

  4. Don’t end the subject line with a period

  5. Use the imperative mood in the subject line (In the body it is optional)

  6. Separate the body from the subject with a blank line

  7. Wrap the body at 72 characters per line

  8. Explain why and what changed, not how

Now, here are some details:

Subject:

  1. The Subject should begin with the issue related to this commit.

For example, if the commit is related to the issue “ARIA-1407”, the subject line should also begin with “ARIA-1407”.

  1. Try to limit your subject to 50 characters, but definitely don’t go over 72.

50 characters is not a hard limit, just a rule of thumb. Keeping subject lines at this length ensures that they are readable, and forces the author to think for a moment about the most concise way to explain what's going on. This limit is used in two very well-managed projects, the Linux kernel, and Git itself, and even GitHub advises you to keep your subject lines at 50 characters:

50_characters_limit_in_github.png

Regarding the 72 characters limit, besides being a widespread practice, GitHub itself hides part of the subject if you pass it, and you have to click the ellipsis icon to see the rest of it:

72_characters_limit_in_github.png

  1. Start the subject line with a capital letter.

  1. Don’t end the subject line with a period.

  1. Use the imperative mood in the subject line.

  • Add mechanism X to improve the performance of Y

 Instead of:

  • Added mechanism X to improve the performance of Y

One reason for this is that git itself uses the imperative whenever it creates a commit on your behalf. For instance, when you merge pull requests on Github:
imperative_mood.png

properly formed git commit subject line should always be able to complete the following sentence:

  • If applied, this commit will <your subject line here>

Body

  1. Separate the body from the subject with a blank line.

  1. Wrap the body at 72 characters per line.

You can do that using vim: https://github.com/tpope/vim-git

  1. Explain why and what changed, not how.

You should explain what changed, and why did it change. Just focus on making clear the reasons why you made the change in the first place—the way things worked before the change (and what was wrong with that), the way they work now, and why you decided to solve it the way you did. The code, with the help of the diff and source comments, should explain how it was changed.

Metadata

The metadata should contain issue tracker info and related stuff. It should be at the bottom of the body, separated from the previous paragraph of the body (if any) with a black line.

The contents of this section are TBD.

(See long version here)

General Recommendation

Please don’t use `git commit -m` to create your commit message, as chances are it will be harder for you to follow these guidelines in this way.

Sample Commit Message

commit_message_example.png

Sources

http://chris.beams.io/posts/git-commit/

http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

  • No labels