Bruno Peeters Technical Blog

When it comes to commit your work to a software versioning system like git, and putting a message to the commit, it feels like for most developers this is something that needs to be done but they don’t want to spend much time on it. You see cryptic messages within the commit message, which doesn’t add any real value to it. When looking at the goal of a commit (message), what is needed to achieve this goal? In the end, when having a proper clean commit with an accompanied commit message, it will eventually help you speed up your development process.

The goal of a commit message

To understand the goal of a commit message, we first need to look at why we have a software versioning system at all into place. A software versioning system, like git, helps us to let evolve a file in a controlled way. That means, we can add changes to the file or roll back changes. In this way changes are always logged and we can go back and forth within the scope of the lifetime of this file.

There are different reasons why we want to understand the lifetime of a file. In the end it is all about communication. By adding context to a commit, by adding a proper message, you help your team members and yourself to understand a change to a file. This will eventually lead to a higher quality of software and will speed up the development process within the team.

Let’s take for example that over some time a bug was introduced within some piece of code. In this case you want to see when and how this was introduced. At the time when the code was added, which introduced the bug, the developer had a good reason to add this code. Now if you’re lucky, the developer is still within the team and you can ask him. If for some reason, he or she isn’t available anymore, you can also try to see if the software versioning system can help you with this.

The scope of your commit

Now we’ve looked at the reason of a proper commit message, let’s look at what a commit consists of. A commit means a bundle of files together that are added to your repository.

In general a commit will have a small set of files that has been addressed, the number of lines of code is small and it all addresses the same topic. Narrowing down the scope of your commit makes it easier for developers to understand the changes. Also when a commit focusses on only one problem, it is easy to role back only one commit that causes an issue.

Try to bundle files, focussing on the same fix or goal in one single commit.

Also don’t check in half done work. When a feature is big, split it up in small logical chuncks that can be commited to the repository.

Don’t check in half done work.

Make sure your code at least compiles before committing it. Going one step further make sure all tests are passing. If there is not already a unit test in place that tests the code you’ve added, create one and add it to the same commit.

Make sure your code at least compiles before committing it.

Which information to add to the commit message

Like said before, the goal of the commit message is trying to understand what the change of the commit is all about. When applying the rules described in the section before, our commit contains now a set of changes that pursue a common goal. Now it is key to have some text that goes along with this set of changes.

Like Simon Sinek’s book which is called “It start’s with why”, it also start’s with why when it comes to commit messages. Why is the change being made? Explain this briefly within the message.

Why is the change being made?

Don’t add long explanations to the commit message. Nobody will ever read long messages, and you might wonder if a commit requires a long explanation if this commit couldn’t be reconstructed in such a way it is better to understand for everyone.

Don’t add long explanations to the commit message

When doing something, you do this for a reason. After a change is being made to a source file, it can be hard to understand what the original problem was the engineer wanted so solve with a commit. Don’t assume that someone who reads the commit understands the original problem. Explain what is trying to be solved.

Don’t assume that someone who reads the commit understands the original problem.

Use the structure as used within a newspaper: the most important text goes up (your title) and the lower you go, the more you describe the details.

Use the structure as used within a newspaper

Style

Like a coding style, you want also to define a certain commit message style within your team. Here you can define the markup of your messages or how the message should be structured. If the whole team uses the same way of communicating, it will be easier to understand the history of a change to a file and come up with a proper fix that won’t introduce any regression.

What you will gain

A good commit message is all about good communication within your team. If you write proper commit messages, it will help you and your team speeding up the development process and software quality since you can easier understand the changes that were made to the software over time.