[git] Commit Messages

I’ve recently thought about git commit messages and wondered about their quality. What makes a good commit message? What makes it helpful? What makes it unclear, unhelpful, or otherwise undesirable? I’m going over a few examples of unhelpful messages I created in the past and likely also link some positive examples. This is — of course — my take on it, and people may disagree or find something else helpful. Also, some project may require more / other information to be present in their commit messages.

Bad Examples

Let’s start off with some bad examples I did in the past. I show the complete message here and link the commit. Luckily, while I dug through the git log, I did not find as many examples as I had expected. Anyway.

• Minor changes (from: https://github.com/tudasc/PIRA/commit/2f0f509c7218f2abd300caa3895f34638181b5ba)
• Worked on runtime filtering (from: https://github.com/tudasc/PIRA/commit/9d3e9eba6a0ca30c4c4f32962756b8814318bb99)
• Small fixes (from: https://github.com/tudasc/PIRA/commit/0f88dec16a2dd2197cb9575f80a77a3ff16e3746)
• Applied formatter. Obscured potentially made changes with that. F***. (from: https://github.com/tudasc/PIRA/commit/d2e9070079606b089c83bb7c346d49b02f2d555f)

Reasons These Examples Are Bad

Unclear: Most of the linked examples are unclear. This makes it terrible to judge which component or behavior of the software was impacted by the change and in what way. So it is unclear in the most wholesome way. As from the list above “small fixes” can mean anything, from a non-functional typo fix to an actual fix of functionality, depending on what the author (from-the-past-JP) meant at the time.

Unhelpful: At least the one about “Worked on runtime filtering” is quite unhelpful, as it does not tell whether it completed the work, addressed issues, which issues are potentially still observed or whatever more info could be given. The final message, while clearly stating what it did, it also is somewhat unhelpful and may be interpreted to use some inappropriate language.

Good Examples

After this handful of bad examples, let’s also look at some good examples. Since I do not want to point to my own stuff as “good examples”, I’ll list a few git commits that I found helpful.

• [CodeGen] Forbid passing a PointerType to MVT::getVT and EVT::getEVT (from: https://github.com/llvm/llvm-project/commit/7fb0c673f38c0ff8913aff811b3b3bcac74b48d1)
• [lldb-dap] fix inconsistent debugAdapterHostname argument name (from: https://github.com/llvm/llvm-project/commit/839f52147c0cdbe7d4590cfdda089f250e5ec119)

Reasons These Examples Are Good

Clear: Both git commit messages I listed above are clear on what the change was. It listed the component, which is helpful in a large mono repo as LLVM is, and what was changed. I have only copied the short description here, so click on the link and read the full commit message. However, even from the short description, the change is clear.

Concise: The git commit message starts with a concise summary of the change. In my opinion, this is as important as a clear and concise description. In particular, this helps when looking at a longer list of commits, e.g., when bisecting a bug or issue.

Helpful: I quoted especially the first git commit message because something that stood out to me in that message was that it mentioned a potential scenario where fixups are needed. This was helpful — yes, I had to make such a fix up to address a compilation error. So this was an immediate help for me.

My Take For git Commit Messages

Over time I have found some takes that I follow for writing git commit messages that I think result in reasonable, or maybe even good, commit messages.

• Provide concise summary line to start the commit message. List affected component if possible (for large repositories). This helps when bisecting larger numbers of commits and digging through history.
• Provide a potentially needed explanation / motivation for the change, but keep it brief. IMHO this should not be a large write-up, but briefly explain the problem.
• Provide the description of the change.
• If applicable, provide potential fall out of this change and what needs to be done as follow-up or if fixes are required.