On Formatting Commit Messages

Raimund Krämer

—

November 12, 2023

commits, conventions, documentation, Git

Many developers invent their own convention for commit messages—if they follow one at all. What many don’t know is that there has been a quasi-standard pretty much since the beginning of Git’s existence. For some developers it is obvious that this convention is to be followed unless another one has been explicitly chosen, but in many teams it feels more like anarchy in the beginning.

Note that I am not referring to Conventional Commits, in case you are wondering. Conventional Commits are one of the most common alternatives to what I call the “default convention”. They are decently wide spread, and are quite commonly chosen for projects, but it can hardly be considered the default or a quasi standard by any means.

The “default” convention

The convention I’m referring to originates from Git’s own as well as the Linux kernel’s development. It is also used by Git itself, in the messages it generates for example when cherry-picking or merging. It is explained and encouraged (although not prescribed) by the official Git documentation.¹ And it is supported and/or expected by many tools and editors—not just legacy ones. Git itself assumes that messages are formatted that way in order to work as expected.

A lot has been written about this default convention before, and anybody who searches the web for a convention for Git commit messages, or even just whether one exists, basically can’t miss either the “default” convention or Conventional Commits. My suspicion is that few are doing that search.

An example

The following example is written like a commit message explaining the main points. The convention is really that simple. For most commits a much shorter message is probably enough—for trivial changes perhaps even just the one-line summary.

Write short imperative summary

After a blank line there can be more detailed info. Note the manual
line-breaks after about 72 characters. Consider explaining the *what*,
the *why*, and the *how*, but especially the *why*.

Some like to add a ticket ID to the summary line like this or similar:
  [ABC-123] Write short imperative summary

- You can use bullet points.
- A link to docs or Stack Overflow can be helpful, too. Longer bullet
  points use a hanging indent.

More info about the bug fix:
https://stackoverflow.com/questions/11828270/how-do-i-exit-vim

This fixes the bug that was introduced in commit c4f3b4b3.

If that looks similar to what you are doing already, maybe you are already following that convention. However, if you were not yet familiar with it, it is very unlikely that you have been following it unconsciously, and you might be missing something. In that case the more detailed explanation below might help.

Writing a good summary

The first line summarizes your change in about 50 characters. Less is better. It’s usually possible to write a shorter summary. Remember that leaving out detail is the whole purpose of a summary.

My personal tip is to go for “verb-adjective-object” sentences (like “Add Czech translation” or “Remove deprecated dependencies”) or “verb-object-reason” (like “Refactor Frobulator for clarity” or “Optimize mainframe download for throughput”). This can help with finding a short but clear summary for your change. If it seems impossible to write a good summary within 50 characters (or slightly more in the odd case), then it might indicate that your commits are not scoped well and actually contain multiple changes.

The summary is written in the imperative mood and does not end with a period. “Upgrade dependencies”, not “Upgraded dependencies” or “Upgrading dependencies”. This is consistent with how Git generates commit messages (“Merge branch …”) and it has been standard practice for a long time, but it is easy to miss if nobody told you before.

Note that Conventional Commits are actually very similar at their core. For example, they also use the imperative, but I have seen many miss that detail as well since one can easily be tunnel-visioned on their syntactical details.

The body adds context

Very small and simple changes can often be described with just a good summary line, but whenever more context is helpful, it belongs into the commit message body. Many comments that you want to add to the source code can actually be added to the commit message instead. Remember that the commit history is searchable.

The message is manually word-wrapped around 72 characters. This leaves some room for quoting and indentation. Most text editors might do fine with longer lines, and yes, we have bigger screens nowadays, but there’s a reason why newspapers still lay out text into columns.

Conclusion

Of course it is up to you which convention you follow. However, if you simply were not yet aware that Git actually has a convention for commit messages, and basically a correct format, then I strongly encourage you to use it. It’s never too late to start forming a new habit.

If your project uses a different convention, follow that instead, but make sure not to unlearn the default. If you have used your own “convention” (if we can call it that) for many years before learning about the convention that has existed for almost two decades, you might experience some cognitive dissonance and feel the need to dismiss it as something outdated. I’d like to encourage you to break through that little obstacle and simply catch up on this habit that someone should have taught you years ago when they thought it is better to not overwhelm you while you were also learning all those new Git commands.