"fixed stuff" and "update" are not commit messages — they're confessions of laziness. Good commit messages are live documentation. Here's how to write them.
Follow the Conventional Commits standard:
type(scope): short description
Types: feat, fix, docs, style, refactor, test, chore
Example: feat(auth): add OAuth login with Google
For non-trivial changes, add a blank line then explain:
Link to the relevant issue or ticket: Fixes #142 or Closes #87. This creates traceability between code and requirements.
Bad: "fixed login bug"
Good: "fix(auth): prevent token refresh race condition on concurrent requests"
Bad: "updated stuff"
Good: "refactor(api): extract validation logic into middleware layer"
Write commit messages as if you're explaining the change to someone who hasn't seen the code. Your future self (and your teammates) will thank you.
Curious how your code and commit practices stack up? Our code roast tool reviews your code quality, structure, and best practices — including naming conventions and documentation patterns.
fix(cart): correct shipping calc introduced in 3f2a9c.BREAKING CHANGE:)Conventional Commits gives you machine-readable history: auto-generated changelogs, semantic versioning, and blame tools all parse feat vs fix. If your team already uses changelog generators or release automation, standardize on it. If not, a simpler "imperative verb + short subject + reason in body" convention still beats ad-hoc messages. Pick one, document it in your repo, and make it a review gate — consistency matters more than the specific convention.
Ideally yes, but the practical rule is stronger: every commit should describe one coherent unit of work that leaves the codebase in a working state. Tiny commits are only useful if their messages stay meaningful. The enemy is not size; it is incoherence: a commit that mixes three unrelated changes is a history-time bomb. It makes reverts impossible and blame archaeology painful.
Subject under 50 characters, body as long as it needs to be. But if the body exceeds a few paragraphs, the change is probably too large. A long body is a signal to split the work. If you must document a complex decision, that belongs in code comments or a design doc, referenced from the commit.
On your own branch before pushing: yes, freely. Squash noisy WIP commits into coherent ones and fix sloppy messages. On a shared branch or after a merge: no, because rewriting shared history breaks everyone else's view of the repo. The rule is simple: clean up before you push, never after.
Yes, more than anywhere else. In six months you will navigate that history to remember why a decision was made, and the discipline transfers directly to team work. The cost is seconds per commit; the payoff is hours of archaeology saved when something subtle breaks.
These tools pair well with our roast to help you improve your code.
Some links are affiliate links — we may earn a commission at no extra cost to you.
