It often happens that I read through GIT logs. It is a great way to check how a project is progressing. You can easily see when features were implemented and bugs were fixed. Unfortunately the logs are pretty useless when commits are randomly done and messages are too fuzzy to make something out.

I recently saw a list of 5 commits by the same author. All with the same commit message: "Modified files.". All had a bunch of files changed without any indication what was really going on. This is obviously wrong and it pisses me off. Not everybody seems to understand the value of a proper commit with a proper message. So I am going to explain some things and give a few tips.

First up are the commits themselves. Make sure the commit has a theme. Like fixing a particular bug or implementing a little feature. Commit as often as you can. Make new commits even for the smallest changes. You can always squash some commits to make it more sensible. Also smaller commits make it easier to merge and revert. Conflicts will be easier to solve and reverts will be smaller so that you don't have to revert all your work. If you work on more than one feature/fix you should use separate branches.

The commit messages are very important. Underneath you'll find a couple of points to keep in mind when typing your commit message. When you follow those points you will get a nice little story in your GIT log and you won't have to stare endlessly at diffs to find out what happens. So here we go:

  • Use proper English so that everybody understands what you mean.
  • Describe what the commit does, not what you did.
  • Include why you made the change.
  • Include references. Things like ticket numbers or links to related sources.
  • Format the message correctly. Tim Pope wrote a great post about that.

A brilliant example are the commit messages in the repository of the Linux kernel. Take for example this commit. It describes the exact nature of the problem, how the commit fixes the problem, who reported it and who signed off on it. The commit itself is relatively small, it changes just a few lines of code. Now most of the time your commit messages wouldn't be that long, but they can be if you need them to be.