Commit messages done the right way

10 Feb, 2022
Xebia Background Header Wave

We have all seen it. You see something in your source code. You do not know why it was added. And you look at the commit history. And then you see: "fix bug" or "add feature name". How helpful is that message?

In this blog post I will address how you can write commit messages that are helpful. And optimized for the reader.

So, why is this important?

Most agile teams need peer reviews. The most common or well known way is via pull requests.
When you introduce a change. For a feature or fixing a bug.

The question your peer reviewer will have is: Why this change was made. And then continues to look at the changes.

You create a pull request on one or more commit messages. A commit describes the why of a change. When you create a pull request you can use these commit messages when you create your pull request.

Example commit

fix input


fix: white spaces on input

Remove the leading and trailing spaces. This will clean the input before we save it to the database.

Issue: #123

This is the difference between writing a commit message. And writing a useful commit message.
Useful commit messages explain why the change was made.

When you create a pull request you can use the commit messages as input. And draft a useful pull request description for your reviewer.

Commit format

I am a big fan of the conventional commits format. But the most important thing is that you write down why the change was made.
Not what the change is.

The changes are already displayed when you do a diff between commits/branches. So describing what has changed does not make sense.
The reason why that is in the authors head. And unless you add it in a commit message that information gets lost.

By doing this you create a better historical overview. And it makes it easier to create pull requests.


When you optimise your commit messages for the reader. The reader does not need to go on a scavenger hunt.
And it creates a better historical overview of why changes are made in your repository.

Joris Conijn
Joris has been working with the AWS cloud since 2009 and focussing on building event driven architectures. While working with the cloud from (almost) the start he has seen most of the services being launched. Joris strongly believes in automation and infrastructure as code and is open to learn new things and experiment with them, because that is the way to learn and grow. In his spare time he enjoys running and runs a small micro brewery from his home.

Get in touch with us to learn more about the subject and related solutions

Explore related posts