How to Write Useful Commit Messages

Effective commit messages simplify the code review process and aid long-term code maintenance. Unfortunately, commit messages don’t get much respect, so the world is littered with useless messages like Fix bug or Update UI.

There’s no widespread agreement about what makes a good commit message or why it’s useful, so I’m sharing my thoughts based on my 20 years of experience as a software developer.

• An example of a useful commit message
• What’s the point of a commit message?
  • Helps your code reviewer approach the change
  • Communicates changes to teammates, downstream clients, and end-users
  • Facilitates future bug investigations
  • Provides information to development tools
• Organizing information in a commit message
  • Put the most important information first
  • Use headings to structure long commit messages
• What should the commit message include?
  • A descriptive title
  • A summary of how the change impacts clients and end-users
  • The motivation for the change
  • Breaking changes
  • External references
  • Justifications for new dependencies
  • Cross-references to issues or other changes
  • Summaries of bugs or external references
  • Testing instructions
  • Testing limitations
  • What you learned
  • Alternative solutions you considered
  • Searchable artifacts
  • Screenshots or videos
  • Rants and stories
  • Anything you’re tempted to explain outside of the commit message
• What should the commit description leave out?
  • Information that’s obvious from the code
  • Critical details about maintaining the code
  • Short-term discussion
  • Preview URLs and build artifacts
• Further reading

An example of a useful commit message🔗

Here’s an example of a useful, effective commit message:

This commit message is helpful for a few reasons:

• It presents the most important information early.
• It explains the motivation and effect of the change rather than just summarizing implementation details.
• It’s succinct and excludes useless noise.
• It cross-references related bugs and commit hashes.

What’s the point of a commit message?🔗

A commit message serves several roles, which I’ve listed below from most important to least important:

Helps your code reviewer approach the change🔗

When you send your code out for peer review, the commit message is the first thing your reviewer sees.

The code review is the most important scenario for a commit message, as effective communication at the review stage can prevent bugs or maintenance pitfalls before your code reaches production.

Communicates changes to teammates, downstream clients, and end-users🔗

Beyond your reviewer, other people on your team want to understand if your changes impact their work.

If you’re working on an open-source codebase or a project with downstream clients, your commit messages also inform your clients and end-users about how your change impacts them.

Facilitates future bug investigations🔗

After you merge your change, your code will live in the codebase for years or maybe even decades. Developers frequently review the commit history to diagnose bugs and to understand the software, so a clear commit message speeds their investigations.

Provides information to development tools🔗

Many development tools scrape information from commit messages to automate software development chores, such as cross-referencing bugs or generating release notes.

Organizing information in a commit message🔗

Put the most important information first🔗

In a long commit message, most readers don’t want to read the entire thing, so put the most important information at the beginning. This allows the reader to stop reading as soon as they reach the information that’s relevant to them.

Journalists call this writing style “the inverted pyramid.” A good news report begins with the details that readers care about most. As the article progresses, the focus shifts toward details that are relevant only to the most interested readers.

Use headings to structure long commit messages🔗

Headings create structure in a long commit message, making it easier for the reader to find information relevant to them:

What should the commit message include?🔗

For a simple change, a one-line commit message could be sufficient. The more complex the change, the more detail the commit message needs.

The following is a mostly-exhaustive list of details that could be useful in a commit message.

A descriptive title🔗

The first line is the most important part of the commit message because it’s what appears in the commit history of most git UIs.

When you print the commit summary using git log --oneline, it prints the first line of each commit message:

$ git log --oneline
fd8902a (HEAD) Combine tests in reviews_test (#421)
32dbf9a Log error information on account handler errors (#420)
dea3e7a Stop using npm scripts to check frontend (#418)
20ec3c6 Upgrade to sqlfluff 3.3.0 (#417)
4383920 Make prettier ignore .direnv directory (#416)
cacf31b Make Nix version of Go match Docker version (#414)
c6489bf Lint SQL in pre-commit hook (#415)

GitHub and other git UIs also show the first line of each commit message prominently in the change history:

Your teammates and users can’t read every line of every change to the codebase, so the title is the primary way that you communicate whether the change is relevant to them.

The title should describe the effect of the change rather than how you implemented it. That is, the “what” rather than the “why” or “how.”

In a change where you add a mutex to prevent a concurrency bug, this would be a poor title:

A better title explains the effect of the change. What’s different about the application now that there’s a mutex?

A summary of how the change impacts clients and end-users🔗

Usually, you can’t capture all of the relevant details about a change in the title alone, so the subsequent lines of the commit message should fill the gaps.

Keep in mind that, for some audiences, their goal is to understand how the change impacts them without having to read the code itself. It could be because they’re an end-user who can’t understand software code, or they might just be a busy developer who doesn’t have time to read every diff.

Ensure that the commit message explains the relevant details of the change even for someone who won’t read the diff itself.

The motivation for the change🔗

After you communicate what the change does, the most important thing to communicate is “why?”

Why are you making this change? How does your change align with the team’s goals? What considerations led you to this particular solution?

Consider this example:

If a year from now, your teammate wonders why the background is pink, they’d read the above commit message and get zero useful information.

Instead, explain the motivation for the change in the commit message:

Good: Explain the motivation and constraints that influenced the change

Change background from blue to pink

Our current blue background makes links difficult to see:

This changes our background to pink because I think that matches our app’s personality, and it makes the links more legible:

The above explanation makes the motivation and reasoning clear. If another developer wants to change the background in the future, they’ll understand the constraints that guided the decision to make the background pink.

Sometimes, a change’s motivation depends on future plans. You may have a grand vision for how a change is just step one of a beautiful new architecture, but your teammate can’t read your mind to see it.

When you send a commit out for review, use the commit message to communicate how the change fits into any larger designs you have in mind.

Breaking changes🔗

If downstream clients will have to rewrite code or change their workflows as a result of the change, the commit message should explain what’s changing and how clients should handle it.

Use recognizable conventions to make it easy for clients to identify breaking changes. Ensure that your process for creating release announcements scans the commit history to surface details about breaking changes.

External references🔗

Link to any external documentation or blog posts that influenced your design or implementation choices.

You shouldn’t dump your entire browsing history into the commit message (for many reasons), but you should link to the non-obvious resources that will help your teammates understand your thinking.

Justifications for new dependencies🔗

If a change adds a new third-party dependency, flag it in the commit message, and explain why you’re adding it.

Dependencies are a long-term maintenance burden and a frequent source of bugs. It’s helpful for your teammates to understand why you’re adding the dependency and how you selected it.

Cross-references to issues or other changes🔗

On most git hosting platforms like GitHub, GitLab, and Codeberg, mentioning an issue by ID like #1234 automatically creates a cross-reference between the commit and the issue. Similarly, mentioning another change by pull request ID or commit hash creates a cross-reference.

There are also auto-closing keywords like Fixes or Resolves. When a commit message includes text like Fixes #1234, GitHub, GitLab, and Codeberg all know to auto-close issue #1234 when you merge the change.

Creating cross-references to related issues and other changes helps teammates and future maintainers understand the context around the change.

Summaries of bugs or external references🔗

When you link to a bug or an external reference, don’t just write Fixes #1234 and expect readers to read the entire ticket discussion, especially when the bug has a long, complex history. Summarize the relevant details for the reader.

Testing instructions🔗

Ideally, automated tests should exercise your changes, but if those don’t exist, explain to your reviewer how to test your code.

Testing limitations🔗

The default expectation is that you tested your commit to your team’s normal standards before sending it for review or merging it in the codebase.

In some cases, it’s impractical to test a change in all the relevant scenarios. If that happens, disclose what scenarios you haven’t tested. It will help your reviewer assess the risk of the change, and it will provide an answer when future maintainers ask, “Did this code ever work correctly?”

./dev-scripts/run-tests --qemu-emulate riscv64

What you learned🔗

Use the commit message to capture what you learned while implementing the change.

You’ll be glad you wrote it down while it’s fresh in your mind, and your teammates will be thankful that you spared them all from tracking down the same information.

You don’t have to be an expert on whatever you’re explaining — admit freely what you don’t understand. You’ll be surprised at how often your explanations help teammates you assumed knew everything.

./jobA | ./jobB

One neat side effect of documenting your lesson is that the act of explaining it deepends your understanding. Sometimes, explaining your solution makes you realize there’s a better alternative you didn’t explore or a corner case you forgot to cover.

Alternative solutions you considered🔗

Often, you begin a change with a naïve solution and find some reason that it doesn’t work. When that happens, help your reviewer and future readers understand why the obvious solution didn’t work.

Ideally, the explanation should live in a comment within the code itself rather than in the commit message. Otherwise, everyone who reads the code will wonder why it’s doing the non-obvious thing.

If it’s a decision that doesn’t have a logical place in the code, explain it in the commit message.

Searchable artifacts🔗

If a change is related to a unique error message, make sure that the text of the error appears in either the commit message or in a bug that the commit cross-references.

Including the error message ensures that if you encounter that error in the future, you can use git log --grep or the search function of your git hosting tool to find past work related to the error.

$ git log  --pretty=format:"%s%n%n%b" --grep "reading 'parentNode'"
Fix unclosed div in index.html

On about 30% of builds, the build was failing with this error message:

  Cannot read properties of null (reading 'parentNode')

It turned out to be caused by an unclosed div in one of our files.

Beyond error messages, think about other terms that you or a teammate might search to find related commits, such as names of components, projects, or client implementations.

Screenshots or videos🔗

For changes to an app’s user interface, videos and screenshots can be helpful, especially if you show the before and after.

Don’t spend hours trying to produce a perfect, Oscar-winning screencast — a simple 15-second demo can make a major difference for your teammates trying to understand the change.

A video should supplement the commit message, not replace it. A rambly, five-minute screencast is a poor substitute for a succinct and well-organized commit message.

Rants and stories🔗

Stories and passionate rants about the code are fun and sometimes informative, so feel free to include them, but save them until the end.

If someone’s chasing a high-priority bug at 2 AM, they don’t want to read 20 paragraphs about your adventure writing this change or your snarky critiques of a bad library.

Present critical details succinctly at the top of the commit message, and append the rant to make it obviously extra credit reading.

Anything you’re tempted to explain outside of the commit message🔗

Sometimes, when someone sends me code to review, they write me an accompanying email to explain background information. If I’m particularly unlucky, they’ll interrupt me at my desk to give me a brief lecture that I’m supposed to remember while reviewing their code.

In these cases, I gently tell my teammate that we actually already have a great place to share this information with me: the commit message!

Resist the temptation to explain details about your change outside of the commit message or the code itself. If you need to set the stage before a review for your reviewer, do it in the commit message. That way, your reviewer will see it, and so will anyone else who ever needs that information as well.

What should the commit description leave out?🔗

It’s better to err on the side of overcommunicating in a commit message, but there’s also value in reducing noise. Look for opportunities to cut unnecessary information wherever possible.

Information that’s obvious from the code🔗

Avoid mentioning facts in the commit message that the code makes plainly obvious. Examples include:

• A list of files you edited
• What APIs you called
• Whether it’s a large or a small change

The reader will trivially learn those details when they look at the code, so you don’t have to spell it out for them.

Critical details about maintaining the code🔗

You should capture crucial details about maintaining the code, but they’re too important to bury in the commit message. Future maintainers might not think to check there when making changes.

If your teammates need to know something about the code, put the information in the code itself, ideally with automated checks to prevent anyone from violating the code’s assumptons.

Short-term discussion🔗

Consider whether the details you’re adding to the commit message are useful to keep in the source history forever or if they’re just ephemeral discussion that’s useful right now.

If the information is only relevant during the code review, add it as a comment in the discussion for the pull request or bug rather than including it in the commit message forever.

Preview URLs and build artifacts🔗

If your continuous integration system produces preview URLs or build artifacts that are useful to your reviewers, they should be easy for the reviewer to access, but it shouldn’t be the author’s job to add them to the commit message manually. Invest in tooling that automatically surfaces the information during the code review.

The more toil you add to the commit message, the more people will perceive it as a mechanical chore rather than an opportunity to communicate useful information.

Consider the lifetime of the build artifacts. If they’ll only remain available for a few weeks, then links to build artifacts become distracting noise in the commit message. They should live in the discussion channel rather than the commit message itself.

Further reading🔗

• “Writing commit messages,” by Simon Tatham, author of the PuTTY SSH client

Pre-order the book

This is an excerpt from my upcoming book, Refactoring English: Effective Writing for Software Developers.

Want to fund this so I can write the full book? Pre-order the book on Kickstarter to support the book.

Pre-Order Now