Commit Best Practices

This page introduces some best practices for commit messages. Taken from this source.

The seven rules:

1. Separate subject from body with a blank line

Helps with git log --online:

$ git log --oneline
42e769 Derezz the master control program

and with git shortlog:

$ git shortlog
Kevin Flynn (1):
      Derezz the master control program

Alan Bradley (1):
      Introduce security program "Tron"

Ed Dillinger (3):
      Rename chess program to "MCP"
      Modify chess program
      Upgrade chess program

Walter Gibbs (1):
      Introduce protoype chess program

2. Limit the subject line to 50 characters

Forces you to be concise. If you can’t summarize changes in 50 characters, perhaps your commits are too large. 50 is a rule of thumb but 72 is a hard limit.

3. Capitalize the subject line

Easy-peasy.

4. Do not end the subject line with a period

Nothing to be said.

5. Use the imperative mood in the subject line

Meaning “spoken or written as if giving a command or instruction”. Examples:

Clean your room
Close the door

This follows gits own built-in conventions. To double-check if you’re writing in the correct mood, insert your commit subject line in the following sentence:

If applied, this commit will

You can relax this restriction once in the body.

6. Wrap the body at 72 characters

Easier to read this way.

7. Use the body to explain what and why vs. how

This is a great example from Bitcoin Core:

commit eb0b56b19017ab5c16c745e6da39c53126924ed6
Author: Pieter Wuille <pieter.wuille@gmail.com>
Date:   Fri Aug 1 22:57:55 2014 +0200

   Simplify serialize.h's exception handling

   Remove the 'state' and 'exceptmask' from serialize.h's stream
   implementations, as well as related methods.

   As exceptmask always included 'failbit', and setstate was always
   called with bits = failbit, all it did was immediately raise an
   exception. Get rid of those variables, and replace the setstate
   with direct exception throwing (which also removes some dead
   code).

   As a result, good() is never reached after a failure (there are
   only 2 calls, one of which is in tests), and can just be replaced
   by !eof().

   fail(), clear(n) and exceptions() are just never called. Delete
   them.