Commit Messages Don’t Matter

Jul 22, 2022

The process of writing "good" commit messages is sacrosanct to some developers. A quick search will pop up dozens of articles on "How to Write Good Commit Messages." Proper style? Formatting. Imperative voice. Capitalization. Hard wraps.

Commit messages don't matter.

Commit messages are probably one of the worst places for documentation and a common source of bikeshedding. And in the modern developer workflow that's centered around pull requests, they've become more and more irrelevant.

Some common objections:

But how will I know at a glance what files have changed? Commit messages are not a good place to put context information about what has changed. Even granular commits will often affect more than one file or folder. What about a bugfix that found its way into a feat: commit? It's better to reference the ground truth – git diff or git blame.

How will I know why a change was made? Information about why and how often have better homes. There's the code review history, the bug tracker, the code comments, and the actual documentation. All of which are probably better places for real knowledge to be stored.

What if lose context we change our other systems (issue tracker, knowledge base, etc.). We won't change our version control system. No data source (including git) is sufficient by itself to document the full context. Important information is stored in pull request descriptions or review comments that isn't stored in the repository. These systems change, and migrations are painful. What if Linux didn't archive it's mailing list?

Won't this make reverting commits more difficult? Reverting commits really only happens near the top of the tree, where diffs are more useful (and truthful) than searching through a reflog. There's no guarantee that reverting will be possible at the single commit level anyway (if not squashed).

Won't this make reviewing code more difficult? While I admire authors who painstakingly break commits up into buildable, reviewable units, this is often not a good use of the author (or reviewer's time). More often than not this work is only for the review stage as commit granularity is lost when they are squashed, rebased, or merged committed. Instead, pull requests are the de facto reviewable unit and workflows should probably be designed around them.

Won't this make git bisecting difficult? Bisect is unaffected (you shouldn't be selecting your "good" and "bad" revisions based on commit message text, but rather a checksum reference from your CI/CD results).

What's the alternative? If you must insist on some aesthetic or workflow policy – I'd suggest enforcing a consistent merge policy – i.e., all changesets must be squashed-merged, rebased (preserving linear history), or merge committed (branch history).

It's much easier to enforce that each merged pull request is buildable rather than each commit (I've rarely seen a CI/CD system that runs integrations tests on each individual commit within a changeset).

Subscribe for daily posts on startups & engineering.