Git Commit Messages Your Future Self Will Thank You For

TL;DR: Good git commit messages explain why a change exists, not what the diff already shows. Put an imperative, 50-character subject line first, add a short body when context matters, and keep each commit focused on one thing. Ten extra seconds now saves a 40-minute debugging session later.

It's 11:40pm. Production is throwing 500s. You open git log and find three commits in a row: "fix", "fix again", "actually fix". The bug is in there somewhere.

Good commit messages aren't about pleasing reviewers. They're a note to the person debugging this next — probably you, six months from now, with no memory of why anything was done.

Why vague git commit messages cost you real time

Git has tools that only work if your history is trustworthy. git bisect hunts a breaking commit by halving the range — but each step asks you "is this commit good or bad?" You can't answer if the messages are noise. Same story with git blame and cherry-picks during an incident.

Here's the thing: the diff already tells you what changed. git show handles that. The commit message is your only slot for the why — the Jira ticket, the flaky test, the customer who reported it.

The anatomy of a good commit message

Most teams settle on a format close to this:

Add retry with backoff to Stripe webhook

The webhook occasionally times out during nightly batch jobs,
so charges were silently dropped. Retries three times with
exponential backoff before failing loudly.

The rules that matter:

• Subject line: imperative mood ("Add", not "Added"), under 50 characters, no trailing period.
• Blank line between subject and body — git treats the first line as a title.
• Body: wrapped at 72 characters, explain motivation and trade-offs, not a file list.
• Reference issues in the footer: Closes #482.

Imperative mood isn't pedantry. It matches what git itself generates ("Merge branch...", "Revert...") and reads like a command the commit applies to the repo.

Conventional Commits: useful or ceremony?

If you work on a team with releases, adopt them. Prefixes like feat:, fix:, and chore: let tools such as semantic-release or changesets generate changelogs and bump versions automatically. The structure also stops people from writing "updates" as a subject.

Solo side project? Honestly, full Conventional Commits can feel like paperwork. A clear subject plus a two-line body gets you 90% of the value. Don't skip the body because you're following a format — the format is the easy part.

Real examples: before and after

• fix bug → Fix null pointer when cart is empty at checkout (then a body: which flow, which error, which PR caught it)
• update styles → Fix button contrast on dark mode to meet WCAG AA (accessibility wins deserve the detail)
• refactor → Extract payment validation from CheckoutController (scope in the subject, reasoning in the body)
• WIP → don't push WIP to shared branches. Squash it or use git commit --fixup and rebase.

One more trick I recommend to everyone: run git commit -v. It opens the diff in your editor while you write the message, so you describe what you actually changed instead of what you remember changing. Small thing. Big difference.

If your team keeps slipping, add commitlint with Husky as a pre-commit hook. Yes, it's a gate. No, it isn't fun — but a rejected message is cheaper than a year of wip commits.

Key Takeaways

• Explain why in the body; the diff already shows what.
• Imperative, under-50-character subject line, then a blank line.
• One logical change per commit — it makes bisect and revert actually usable.
• Adopt Conventional Commits on teams with automated releases; skip the ceremony on solo projects.

Frequently Asked Questions