How To Write Good Commit Messages

Good commit messages make a big difference in your team's ability to stay on top of changes to your codebase. However, coming up with useful and understandable messages is often easier said than done, especially when you’re hard at work. Luckily, there are a few tricks to getting your commit messages on track, not the least of which involves putting in some effort in the first place.

Avoid making meaningless commit messages.

One of the quickest ways to cause confusion and frustration among contributors to your project's codebase is to create numerous commits with poorly thought-out messages. Vague, overly brief, or otherwise incomprehensible commit messages can completely derail your team's efforts to collaborate on your project. Even worse, meaningless commit messages can keep you from backtracking through your own work.

Whenever you need to go back over your own commits and revise your changes, well-structured, clear commit messages will quickly show their worth. Instead of being stumped by old placeholder commit messages such as "Changed file," you will be able to track down specific changes with ease and focus on the work you intended to do in the first place.

We have a saying at Mergify, which is: be nice to the future-you.
Take care of yourself in the future: when you'll dig through your changes, you will thank your past-you for writing these thoughtful commit messages.

Keep your commits small

The size of your commits can come to define the usefulness of your commit messages. Large commits usually involve large numbers of changes that can have sprawling effects on your project. This makes those commits more difficult to get right. It also makes them much harder to correct later on, as the many elements of your code that were modified at once are far messier to document in a single commit message than they might be in a group of smaller ones.

The result of this mistake is similar to that of making meaningless commit messages: You will end up manually reviewing your code changes to get work done down the line. This wastes time and is way too frustrating to ignore.

Update your commit messages to make them more descriptive

Although you may already know the importance of creating clear, useful commit messages, the process of actually doing so every single time you commit could still fall by the wayside every so often. Whether you were having a tough time working on a complex issue or needed to reach a deadline and came up with a commit message that doesn't look right, you can always amend your previous commit using the git commit --amend command.

Using the --amend option will replace your previous commit with a new one, so you should generally avoid using it on commits that are already published. To go back further in time and clean up your commit messages, you can give the git rebase command and the git reflog command a try. The former makes it possible for you to squash multiple previous commits into a single one while modifying each commit message manually or automating the process. The latter option keeps track of all commits regardless of how they are (or aren't) referenced, allowing you to revert your commit changes to a previous state with relative ease.

Aim for consistency

Writing Git commit messages can take a lot of practice to get just right. However, you can start on the right foot by simply consistently writing your own commit messages. When each message follows a simple, repeated format, it becomes much easier to decipher what was meant, even if you were not quite sure how to phrase it at the time.

A simple format worth adopting for your own Git commit messages' subject lines is: a verb (the action you took) + a noun (the part of the project your action was intended to affect) + a reason (why you took action in the first place).

Using a framework such as Conventional Commits is also helpful in following clear guidelines and a specification providing human and machine-readable meaning to commit messages. You can even leverage Mergify to validate that your pull requests follow such a pattern.

The basic formula above results in readable subject lines that are descriptive without verging on biographical. Any necessary explanations can be included after a line break. Standardized details that you feel are important to include in every message can be mentioned at the end as well. When applied to a team setting, this approach can quickly save you hours of back-and-forth between contributors. The alternative is a laundry list of messages of varying lengths with vastly different meanings. Stay consistent, and you’ll soon see the benefits.

Your Git commit message matters

Although it might not seem like it as you toil away at your code, the written messages you add to your commits make all the difference in maintaining your project for years to come.

With well-written commit messages, you can map out all of the changes you’ve made to your project over time and maximize Git's ability to do what it was made for—tracking changes to your codebase over time for later perusal and use. To learn more about making this and other GitHub repository management processes easier for your team, reach out to our experts at Mergify today.