Page History

...

Below you will find seven good rules to write great commit messages. But before, please remember this specific Magnolia rule(s)

Use a well descriptive subject

...

The seven rules of a great git commit message

1. Separate subject from body with a blank line

...

Firstly, not every commit requires both a subject and a body. Sometimes a single line is fine, especially when the change is so simple that no further context is necessary. For example:

    Fix typo in introduction to user guide

  

Nothing more need be said; if the reader wonders what the typo was, she can simply take a look at the change itself, i.e. use git show or git diff or git log -p.

If you're committing something like this at the command line, it's easy to use the-m switch to git commit:

    $ git commit -m"Fix typo in introduction to user guide"

  

However, when a commit merits a bit of explanation and context, you need to write a body. For example:

    Derezz the master control program

MCP turned out to be evil and had become intent on world domination.
This commit throws Tron's disc into MCP (causing its deresolution)
and turns it back into a chess game.

  

This is not so easy to commit this with the -m switch. You really need a proper editor. If you do not already have an editor set up for use with git at the command line, read this section of Pro Git.

In any case, the separation of subject from body pays off when browsing the log. Here's the full log entry:

    $ git log
commit 42e769bdf4894310333942ffc5a15151222a87be
Author: Kevin Flynn <kevin@flynnsarcade.com>
Date:   Fri Jan 01 00:00:00 1982 -0200

 Derezz the master control program

 MCP turned out to be evil and had become intent on world domination.
 This commit throws Tron's disc into MCP (causing its deresolution)
 and turns it back into a chess game.

  

And now git log --oneline, which prints out just the subject line:

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

  

Or, git shortlog, which groups commits by user, again showing just the subject line for concision:

    $ 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

  

There are a number of other contexts in git where the distinction between subject line and body kicks in—but none of them work properly without the blank line in between.

...

...

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.

...

For example, the default message created when using git merge reads:

    Merge branch 'myfeature'

  

And when using git revert:

    Revert "Add the thing with the stuff"

This reverts commit cc87791524aedd593cff5a74532befe7ab69ce9d.

  

Or when clicking the "Merge" button on a GitHub pull request:

    Merge pull request #123 from someuser/somebranch

  

So when you write your commit messages in the imperative, you're following git's own built-in conventions. For example:

...

This commit from Bitcoin Core is a great example of explaining what changed and why:

    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.

  

Take a look at the full diff and just think how much time the author is saving fellow and future committers by taking the time to provide this context here and now. If he didn't, it would probably be lost forever.

...