How often have you found commit messages in your Git history to be uninformative? Or alternatively, wordy rambles that are slow to read — and may well not have the information you need anyway?

Headline + Bullet Points is an approach I’ve found to make Git commit messages informative and fast to write.

Having worked with multiple codebases from small to large, I’ve seen a variety of approaches to commit messages:

1. Meaningful headline.
   • Okay for minor commits, but for more impactful work this lacks useful context of what changes were made and why.
2. Narrative.
   • Verbose and slow to read; sometimes provides the necessary context, but just as often rambles about minor details instead.
3. Uninformative headline, or just referring to an issue number.
   • Sigh.
4. Headline + Bullet Points.
   • Quick to read, easy & fast to write; maximizing the likelihood that devs will record useful info about the change.

The case against narrative

Observing developers writing commit messages (and internal docs such as Wiki), it’s clear that narrative is a struggle for many to write.

Commit messages and docs are likely to meander around what the developer was thinking most about — generally the finest technical details and edge cases.

Practically this results in ‘narrative’ doc written by devs frequently tending to omit business/ domain context, reasons for change, impacts or surrounding systems.

Worst of all, narrative is slow to read; even when perfectly written.

Headlines + Bullet Points

Headlines + Bullet Points are quick to convey useful information, in a form that is terse yet easy to read.

What might this look like in a Git commit message?

improve Buffer Cache Management & logging

- change 'tryDrop()' to skip immediately, if lock unavailable
- move BufferCache logging to a separate logger
- attach BufferTrim.Unsuccessful -> Preemptive Flush of oldest buffers

The key elements are:

1. Meaningful headline.
   • Summarize the change being made, and to what component.
2. Bullet points.
   • Identify important specific elements being changed, or explain why changes are being made.
3. Provide higher-level context.
   • Allow changes to be recognized and impacts assessed for relevance from the commit message, without requiring developers to pore over the code.

Headline + Bullet-points bypass a lot of developer struggles with writing narrative; by allowing a simple headline and then, well, cutting straight to the point.

One last note — the above style is informed by readability research; studies find lowercase words faster to scan & comprehend. While I don’t use this in narrative, leading titles & bullets in lower-case really seems to make them easier to read.

See Also

Other thoughts on commit messages:

• https://initialcommit.com/blog/git-commit-messages-best-practices
• https://thoughtbot.com/blog/5-useful-tips-for-a-better-commit-message
• https://www.lesswrong.com/posts/dEcHid7tZPDNvhL4k/do-you-like-bullet-points
• https://copyblogger.com/writing-bullet-points/

Lower-case being easier to read:

• https://docs.microsoft.com/en-us/typography/develop/word-recognition
• https://link.springer.com/content/pdf/10.3758/BF03333407.pdf

Discussion on Hacker News:

• https://news.ycombinator.com/item?id=31173484