How to write a good commit message?

by Michael Tremer, March 5, 2013

Do you like what you are reading? Subscribe to our newsletter and don't miss out on the latest...   Join Now

The development team of IPFire grows bigger and bigger. We are very happy with that, but there is always a downside: How to manage a big team? How can we see what everyone is up to? How can we make working with each other more easy?

I think that it is very important to write good commit messages, because they serve multiple and important purposes at the same time. The most important one of them is to keep track of what has been done in the distribution. But there are also a lot of things they are useful for, you don’t see at the first sight:

  • Good commit messages make the reviewing process much faster. It should be crystal clear what the patch tries to fix, enhance, make better, so the maintainer does not need to waste time to figure out what is going on.
  • Good commit messages make it easier to write a good release note.
  • Good commit messages will help future maintainers (it could be you!) to find out why a particular change was made and how it has been implemented.
  • Good commit messages help new maintainers to understand how development is done in a project.
  • Bad commit messages are essentially worthless. It would be even better to not fix a problem than having bad commit in the project!

There is no 100% correct template for a commit message. The most important thing to keep in mind is being consistent with the other commits in a repository. Try to understand how the git history helps you to understand a project’s history and you will easily find out on what to focus on your own message.

Your fellow programmers are the people who are reading the commit messages. Not the end users of the project, so you don’t need to cut out technical details. Document properly what you have done so they will understand within seconds.

It is also a good idea to add references to a commit message, which may point to a further discussion, a ticket in the bugtracker or more documentation from upstream.

I hope this helps you folks when you write your next commit message. Let this be enough of the theory behind it. Here is an example:

Summary of what the commit is about

Describe your motivation to create this patch and what you try to
archive by it. This is called the body and a line in the body should
not exceed 72 characters. That's because terminals are usually 80
characters wide, but the body is indented by 4 characters and we give
it additional 4 characters on the right, too.

Split paragraphs with a blank line.

Write in the present. "Fix bug" instead of "Fixed bug" to be consistent
with the messages that git creates on its own when reverting or merging

Add anything else one should know to understand this commit or
to bring it into context:

 - Bullet points are always helpful to list things.
 - You may also use asterisks or hyphens like in this example.
   Just be consistent.