Writing a Git Commit Message Your Future Self Will Thank You For

TL;DR: A solid git commit message leads with a short imperative subject line, then uses the body to explain why the change exists — the diff already shows what changed. Adopt Conventional Commits if you publish versioned releases, and amend or squash your messy work-in-progress commits before you push, not after.

Six months from now, someone will run git blame on a line you wrote today. They'll see the code, a timestamp, and one lonely string of text that explains nothing. That string is often the only context left after a rebase, a repo migration, and two job changes.

Step 1: Write the subject line as an instruction

Treat the first line like a command you'd hand a colleague: Add retry logic to the upload worker. Not Added retry logic. Not upload worker changes. Not fix bug.

The rules that actually matter:

• Imperative mood. Git itself uses it — "Merge branch 'main'", "Revert…". Match that.
• Stay under 72 characters. GitHub truncates around there, and git log --oneline gets ugly fast.
• No trailing period. Saves a character, reads cleaner in lists.
• Prefix the area in big repos. auth: rate-limit failed logins beats a bare sentence when you have forty services.

My slightly unpopular take: a commit that says only fix or wip should fail review. It's not gatekeeping, it's basic hygiene.

Step 2: Use the body to explain why, not what

The diff shows what changed. The body should cover the problem you hit, the approach you picked, and what you rejected — especially if it looks obvious in hindsight.

Retry Stripe webhooks three times before failing

Stripe retries on its side, but our handler timed out at 10s while
Stripe's window is 30s, so deliveries looked failed when they weren't.
Three retries with backoff covers the gap without double-charging.

Considered raising the timeout instead; rejected because the 10s limit
comes from the API gateway, not us.

Two formatting notes. Leave a blank line between subject and body — Git treats the first paragraph differently, and tools like git log --pretty=%s depend on it. Wrap the body around 72 characters so it survives terminal widths and email archives.

Step 3: Decide on a Git commit message convention (or skip it)

Conventional Commits gives you feat:, fix:, chore:, docs:, refactor:, test:. The payoff is automation: semantic-release and changesets read those prefixes to bump versions and generate changelogs. Breaking changes get a ! or a BREAKING CHANGE: footer.

Skip it if your team never ships versioned releases. Enforcing a format nobody parses is pure ceremony, and commitlint plus husky hooks annoy people more than they help on a three-person codebase. Once you're past roughly five regular contributors, the tooling earns its keep.

Whatever you choose, if you haven't settled on a convention yet, just pick one and write it in CONTRIBUTING.md. Unwritten rules are the worst kind.

Step 4: Clean up before pushing

Your commit history is a draft until it's pushed. Use that.

• git commit --amend fixes the message or contents of the last commit.
• git commit --fixup=<sha> followed by git rebase -i --autosquash folds a fix into the right place.
• git rebase -i HEAD~5 lets you reword, squash, or drop commits before anyone sees them.

Rewrite your own local history freely. Never rewrite a branch someone else has pulled — that's how you spend a Friday debugging someone else's force-push. And keep one logical change per commit; git bisect is useless if a single commit touches the auth layer and the CSS.

Key Takeaways

• Subject line: imperative, under 72 characters, no period.
• Body explains why, plus what you considered and rejected.
• Conventional Commits pays off only when you automate releases with it.
• Amend, fixup, and squash before pushing — history is a draft until then.

Frequently Asked Questions