Have you ever looked at a change log in your source control system, such as git, and said to your self…

”WTF is this? What does it do and why?”

This post will outline how to write a good commit message in git.

First of all, we need to understand why we write a commit message at all.

What is the purpose of a commit message?

Having a change log that consists of well written messages makes it easier to understand what is happening and enables you to understand why.

As summarized by the people working with Erlang/OTP, a good commit messages serve at least three important purposes:

• To speed up the reviewing process.
• To help us write a good release note.
• To help the future maintainers of the code to find out why a particular change was made to the code or why a specific feature was added.

Who-T lists three questions that a good commit message should answer :

• Why is it necessary?
• How does it address the issue?
• What effects does the patch have?

Before you commit your changes

There are a number of things that you should do before committing any changes to your git repository.

Logical change sets

Make sure that what you are about to commit is logically connected. If you have been working on several different issues during a time period then you should make sure to not group all changes into one big commit. Instead, separate changes for each issue into separate commits. This will make it easier for others to understand what is happening and it also makes it possible to revert a commit at a later stage should it be needed.

Remove white spaces

It is also recommended that you don’t commit any white space errors, e.g. trailing white spaces at the end of the line which are not needed. Git provides an simple way to prevent this. Simply, before you commit, run git diff –check. This command will identify potential white space errors.

Commit only what is needed

You should only commit files and code that is needed.

If you don’t need a file then don’t commit it.

If you don’t use a certain piece of code then don’t commit it. I.e. don’t commit dead code or commented out code.

Readable code

Before committing you should make sure that your code is readable, i.e. well formatted. If you have some code guidelines that you should follow then make sure that you do.

This will make it easier for others (and your self in the future) to review and understand the changes.

Test and verify the changes

Make sure that you have tests for the bug you are fixing and/or the new features your are adding.

Do I need to say that you make sure that your entire test suite passes? Just so you haven’t messed up anything else.

Once you got all of this under control then it is time commit your changes and write your commit message. So let’s continue with just that…

Structuring a commit message

The most important part is to understand that the commit message is mainly for the other people, so they should be able to understand it now and six months later. With this in mind let’s continue.

A well structured commit message has at least two parts.

• a single short line in less than 50 character line which summarizes the change
• a more thorough description to why you’ve done it or what problem it solves

In between these two parts you should have a blank line.

The first line

Some few tips of the first line…

• Must only be one sentence.
• Use the imperative present tense in these messages. In other words, use commands. E.g. use ”change”, not ”changed” or ”changes”.
• Terminate the first line with two newlines to get the blank line.
• Start with a capital letter unless it starts with a lower-case symbol or identifier.
• Don’t use a trailing period either.
• Try to limit you message to 50 characters but don’t exceed 72 characters.
• Prefix the first line with a tag if it makes it easier to know to which part of the module the commit applies.

The main description

Some tips for the more thorough description

• Make sure the commit message is meaningful.
• Include a motivation for the change and contrast its implementation with previous behaviour.
• Use normal prose, normal punctuation and capital letters where appropriate.
• Can be empty if the change is self-explanatory. E.g. ”Add DOAP file”.
• Just as the first line, use the imperative, present tense.
• When committing code on behalf of others use the –author option, e.g. git commit -a –author ”Joe Coder <joe@coder.org>”.
• Add a ”Signed-off-by: Your Name ” line to the commit message (or just use the option ”-s” when committing) to confirm that you agree to the Developer’s Certificate of Origin

A commit message template

Tim Pope has created the following template:

Short (50 chars or less) summary of changes

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 an email 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); tools like rebase can get confused if you run the
two together.

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

– Use a hanging indent