The bug was not in the current pull request. It had arrived three months earlier, folded into a commit with the message update logic. The code looked reasonable enough, but nobody remembered why one branch handled cancelled orders differently. The ticket link was gone, the reviewer had moved teams, and the only remaining clue was a short line in Git history that said almost nothing.
That is when commit messages become less like paperwork and more like kindness to the future. Most of the time, we write them at the end of the work, when we are tired and ready to move on. But the person reading them later may be debugging production, preparing a rollback, reviewing a security concern, or trying to understand why the code chose one trade-off over another. A meaningful commit message is a small note left for that person.
A good commit subject answers what changed. A better commit body answers why it changed. The difference matters because code already shows much of the what. The diff can tell us that a validation moved, a query changed, or a feature flag was added. It cannot always tell us the pressure behind the decision: a customer data shape, a rollout constraint, a backwards compatibility promise, or a bug that only appeared after retries.
This does not mean every commit needs an essay. Small commits can have small messages. Fix typo is enough when the change is truly a typo. But when a commit changes behavior, architecture, data flow, permission, performance, or failure handling, a few extra lines can save hours later. The message should carry the context that the diff cannot hold comfortably.
I like commit messages that are specific about intent. Instead of improve caching, write cache product summaries by locale to avoid cross-language reuse. Instead of refactor service, write extract refund policy from HTTP handler before adding provider retry logic. Instead of fix bug, write reject duplicate webhook events with existing payment id. These messages do not need fancy language. They need enough shape for the next engineer to search, skim, and trust.
Meaningful messages also help review. A pull request can contain several commits that tell a story: add coverage for current behavior, extract pure parser, wire parser into route, remove old branch. That sequence helps reviewers understand risk. It separates safety steps from behavior changes. It makes rollback less frightening because the team can see which commit introduced which movement.
There is a quiet emotional benefit too. A clean history reduces the feeling that a codebase is a pile of accidents. When commits explain decisions, the code feels inhabited by people who were trying to solve real problems under real constraints. Even when the old decision is no longer correct, the team can change it with more respect because it understands the context that once made it reasonable.
Bad commit messages often come from rushed workflows, not bad character. Teams squash too much into one change. Tools auto-fill vague text. People treat Git history as private scratch space instead of shared memory. Review focuses only on the final diff. Over time, the history becomes technically present but practically silent. Then every investigation starts from source archaeology instead of a conversation with the past.
A useful commit message habit can stay simple. Use an imperative subject. Keep it concrete. Add a body when the why is not obvious. Mention constraints, trade-offs, or important non-goals. Link the issue if the workflow uses issue tracking. Avoid vague words like update, changes, cleanup, and fix when the object of the change matters. Write for someone who understands the codebase but was not in the room.
AI can help here, but only if it reads the diff and the intention. A generated message that summarizes changed files without understanding why is just prettier vagueness. A good assistant can propose a subject, list behavior changes, and ask what context is missing. The engineer should still decide what future readers need to know. The commit message is not only a description of code. It is a record of judgment.
The art of a meaningful commit message is modest. It does not ask us to become historians every time we type git commit. It asks us to leave enough light for the next person walking through the same hallway. If you have ever been rescued by one clear line in Git history, you already know how generous that small discipline can feel.