Why git commit messages matter

We all know and love (or hate) git. Not git the term of insult with origins in English denoting an unpleasant, silly, incompetent, annoying, senile, elderly or childish person. But git the distributed version-control system for tracking changes in source code during software development.

The thing we love (or hate) most seems to be writing meaningful commit messages. I mean, come on! Who want’s to clearly describe each and every commit so others can easily understand what the heck is going on? Just read the code, right?

Me, myself and I

Well, when you’re coding by yourself indeed it doesn’t matter how your commit messages look like. Since you are your own reviewer you can -m “what the commit” till you see blue in the face. But when you are part of a team working on the same codebase, writing meaningful commit messages might actually help productivity.

Making commit messages read like an outline (a general description or plan showing the essential features of something but not in detail) will help others understand more quickly what the changes are about. This goes for the git flow development style (for example when reviewing a merge/pull request) but just as well for trunk based development (when reading the commit history).

A logical unit of work

Each commit should represent a logical unit of work, making it a snapshot of the state of the project. Often git commit is (mis)used or (mis)interpreted as a “Save”, leading to a lot of states being captured without clear value or descriptions. A commit message like “Add line 17” doesn’t really denote a useful state change.

Sometimes you see commits being (mis)used or (mis)interpreted to function as trigger, mostly in continuous integration and continuous delivery/deployment (CI/CD) scenarios, leading to commit messages like this:

git log --oneline

40924fg 1
e21ea41 2
69fd101 hello
1b7e869 hello
b490172 f1
eddfe8e f1

And although a commit message generator like http://whatthecommit.com/ is a good laugh, the jokes grow old really fast when you’re coding on a daily basis.

A little tedious as it might be, a team is better off writing meaningful commit messages.

Use active language (as if you are giving orders to the codebase to change its behaviour)

Each commit message should use active language, preferably starting with a verb. For example “add super functionality” instead of “added super functionality. When a reviewer looks at the first message he/she/it consciously or unconsciously registers a sense of change, urgency if you wish. It will make a reviewer pay just that little bit additional attention to the work at hand. It feels like something is happening (“add”) as opposed to something has happened (“added”). Look sharp! is what the brain is thinking for a split second. A small mental switch is flipped.

Git being git you can do whatever you like locally, creating your own personal commit message mess but consider rebasing all bs messages into something useful when pushing to a remote (or git send-email) that is contributed to by others.

Devilish

You might wonder: Why put so much emphasis on these details? That’s easy, because the devil is in them. When you’re a regular driver a little throttle lag doesn’t really matter. In fact it often goes unnoticed (depending on how little that little lag is of course). But when you’re a Formula 1 driver the littlest lag is killing and might make the difference between winning and driving a bus.

Likewise if you want to play in the IT Champions League those commit messages matter.

“A Best Practice if you please”

Consider squeezing the most out of your git commit messages, using a convention. By standardising you can start building a flow around it and leverage the power of automation, for example: automagically generate a CHANGELOG or trigger a(nother) pipeline. Your imagination is the limit.

Some more reading? Try Conventional Commits. Or Commitizen.