Git Best Practices: How to write a good commit message - nissle/abcd GitHub Wiki

This wiki page provides guidance on how to write (good) commit messages that provide many benefits for the team as we collaborate. These guidelines are pulled from various sources, but primarily are based on this guide:

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

To summarize the article:

  1. Commit often. Each commit should only contain one logical change.

    • To reiterate: changes should be atomic. Commit single logical changes frequently as you work.

  2. Every commit message shall have a subject line that:

    • Starts with an uppercase letter
    • Does not end in any punctuation
    • Is 50 characters or less (give or take 5 or so characters). The git documentation encourages this, too. See the discussion here: https://git-scm.com/docs/git-commit
    • Is written in the imperative voice, e.g. "Add test to verify first prize amount" and not "Added test to verify first prize amount"; past tense is discouraged.
    • Starts with an action verb: Add, Remove, Move, Fix, etc. make for good words to start with.

  3. The subject line is followed by a blank line.

    • This habit is rewarded by good integration features in GitHub and enhances the readability.

  4. The subject and blank line is followed by a body that explains why the change was neccessay and what your approach was.

    • This helps make pull request reviewing something that can be done independently without a discussion between the reviewer and the reviewee.
    • The how/what is explained by the diff and is generally not necessary to be explained in the body.

  5. The body uses proper grammar, punctuation and is wrapped at 72 characters.

    • The wrapping at 72 characters prevents logs from requiring horiztonal scrolling (which no one likes).
    • Lists use dashes or asterisks (-, or *) for lists where each element is separated by a blank line.

  6. The body is followed by yet another blank line and a reference to the issue that it resolves or relates to.

Example of the format of a good commit message:

This is taken from the linked blog post:

Summarize changes in around 50 characters or less

More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of the commit and the rest of the text as the body. The
blank line separating the summary from the body is critical (unless
you omit the body entirely); various tools like `log`, `shortlog`
and `rebase` can get confused if you run the two together.

Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.

Further paragraphs come after blank lines.

 - Bullet points are okay, too

 - Typically a hyphen or asterisk is used for the bullet, preceded
   by a single space, with blank lines in between, but conventions
   vary here

If you use an issue tracker, put references to them at the bottom,
like this:

Resolves: #123
See also: #456, #789

For more examples of really good commit messages, see the Linux kernel or Git itself: