Whenever you use a versioning system such as Git, you have many possible ways of organising everything. The Goal of such a versioning system is to keep track of changes, but how easy it is to find a specific change mostly depends on how you use it. That is why in this blog post I will discuss the way I like to write commit messages to guarantee a clear, readable and easy to track history.
Having good commit messages is essential to find out what and why things have changed in a commit. While it is possible to see what has changed by looking at the diff, it is easier to be able to do this merely on the commit message.
I have seen many commit messages that leave you in the dark such as “update” or “cleanup” and don’t state anything useful, which makes you wonder why they even bothered to write a commit message. Others that I have seen only included an issue number, which is good for tracking, but still pretty useless.
In the past I always had a verbose commit message stating every file that was changed and why that file was changed. While this makes it very easy to see why a file has changed, it is very hard to write commit messages like this because I easily forgot why a file had changed. This would however be solved by committing often, which is a good practice anyway. I have however moved to a more compact system where I always state the following:
- A reference to the issue number that this belongs to.
- A short descriptive one-line message summarising the change.
- A longer list of changes that are made if the single line was not sufficient.
An example of such a message:
HIVE-23 Update configuration of I/O Connection. - Remove obsolete inputs and outputs. - Add a list of addresses. - Update GUI and Json.
The reference to the issue number allows for easy tracking in both directions. The one-line message enables compact overview of a list of changes, while the longer list allows for a more in depth overview if required.