When committing code, it's important to clearly communicate the changes you're making.

It helps your teammates understand what you're doing, but also helps you keep track of changes when looking through git history.

The worst thing to see when looking through git history is a message like this: format code. I mean yes it says you formatted the code, but it's unlikely that's all you did in that commit. My only option at this point is to open up the commit and try to go through the change set to see what actually changed.

It's a nightmare.

A good commit message can address this problem. But, how do you write a better commit message? It turns out with a little structure, it's straightforward.

These 5 things have helped me write better commit messages.

Clear and Concise Subject Line

A good subject line can make all the difference.

If done right, it should provide enough information to explain the gist of the change at a glance. I should be able to search through the git history quickly to find what I'm looking for.

Adding a Commit Type

A commit type is a short prefix on the subject line that helps categorize the change.

You might have categories like: fix, feat, chore, etc.

Ideally your team would agree on a subset of words to describe all the changes in your repo. An easy way to get started is to use a tool like commitizen. It walks you through a few steps when you commit code and formats your messages into these categories.

Using a Message Body

If you have a bigger commit that can't be explained in a single line then use a message body.

If used right, a message body can provide context to help explain the change set better. It's not always needed, but it can be really helpful in certain situations. The next two points are good examples of how to use a message body.

Explaining Why a Change Was Made

A commit message should explain why you made a change, not how you made it.

It's pretty common for commit messages to include all the changes that were made as part of the commit. The problem with this is that it's redundant. I already know what changes were made by looking at the change set. There's no reason to repeat that information in the commit message.

Explaining the Effect of the Change

Similar to the above point, it can be good to explain how the change will affect the codebase.

Often times, I've found myself needing more context for a change to some part of the code. It can be convenient for that information to be part of the commit message. If it's not, then my only option is to reach out to the developer that made the change.

Best case, it's a small waste of time for the other developer and me.

Worst case, that developer no longer works at the company, so there's no way to get more information about the change.

Example

Time to look at an example to put everything together.

Let's say that I have an application that's using the 3rd party package: the-best-package. We're on version 1.2.3 of the package. The problem is that I need to bump the package a major version to 2.3.4 to address a performance problem. A good commit message to handle the following might look something like:

perf: update `the-best-package` to v2.3.4

Bumping the package `the-best-package` a major version to fix performance
throughout the app. All exports are asynchronous now and handled with proper
Promise logic.

The commit message explains the change in a short subject line and then expands on that change in the body. That said, you won't need to have a subject and body for every commit message. Sometimes a message like: fix: sign up form password length validation is enough to get the point across.