Conventional Commits
Write commit messages that are worth reading.
- Published
- Dec 27, 2025
- Length
- 4 min read · 1,008 words
- git
- conventional commits
- software engineering
- code review
- developer productivity
- release automation
Have you ever opened git log looking for an answer, and found a wall of noise instead? Every message says something like "update", "fix", or "final fix v2", and now you have to open the diff to work out what actually changed.
Here is the version that greets you at 2am while production is down:
commit 3a1f9d2
Author: handikatriarlan <[email protected]>
Date: Fri Dec 27 23:55:00 2024
fix again
commit 1b2c3d4
Author: handikatriarlan <[email protected]>
Date: Fri Dec 27 23:40:00 2024
probably fine now
commit 9e8f7a6
Author: handikatriarlan <[email protected]>
Date: Fri Dec 27 23:30:00 2024
final fix, please
If that looks familiar, you are in good company. Everyone passes through this phase, where the commit message is just a formality that gets you past git push.
But a commit message is the cheapest documentation you will ever write, and it is the documentation you are guaranteed to need. Conventional Commits gives it a structure that is both readable by machines and pleasant for humans.
What Conventional Commits Is
Every message follows one shape:
<type>(<scope>): <short description>
That is the whole idea. With a fixed prefix, a message stops being a mood and starts being data. It becomes sortable, greppable, and feedable into release notes.
The type says what kind of change this is. The scope says where it happened. The description says what it did, in the imperative mood, without a trailing period.
Compare these:
update stuff
fix(api): return 500 when token expires
fix(api): return 401 when token expires
The first one tells you nothing. The second and third can be searched, filtered, and, critically, told apart. That is the difference between a repository and a graveyard.
The Commit Type Dictionary
The specification defines a handful of types. Most teams add one or two of their own later, but start here.
| Type | Use it for | Example |
|---|---|---|
feat | A new feature visible to users | feat(auth): add passkey sign-in |
fix | A bug fix | fix(cart): correct total when a coupon applies |
docs | Documentation only | docs: update the local setup guide |
style | Formatting, no logic change | style: normalise indentation in the css files |
refactor | Code restructured, behaviour unchanged | refactor(user): simplify validation logic |
perf | A change made for speed | perf(query): index the incident lookup |
test | Adding or changing tests | test: cover empty cart totals |
chore | Maintenance with no source change | chore(deps): bump laravel to 13 |
build | Build system or dependencies | build: switch bundler to turbopack |
ci | Continuous integration configuration | ci: run migrations before e2e |
Two rules keep this honest:
fixneeds a real reproduction. Afixcommit means something was broken and now it is not. Refactoring that happens to touch the same line is arefactor.styleandchorenever touch behaviour. If a reviewer has to ask "does this change what ships?", it is not astylecommit.
The Part Most People Skip
Type alone is not enough. The message body is where a commit earns its keep.
Keep the subject line short
Aim for roughly 50 characters. Git's own tooling historically truncates around there, and a subject that survives truncation intact is a subject written with intent.
Write the imperative mood
add rate limiter # good: describes what the commit does
added rate limiter # awkward
adds rate limiter # wrong: a description, not an instruction
Put the why in the body
The diff already says what changed. The body is where you record why you did it: the bug report, the constraint, the approach you rejected. This is the part nobody else can reconstruct six months later.
fix(auth): stop refreshing tokens that are still valid
The refresh endpoint issued a new token on every request, which
invalidated the previous one on any client running two requests in
parallel (see issue #412). Now we only refresh inside the last 60
seconds of validity.
Add footers for the tools
BREAKING CHANGE: token payload no longer includes "sub", use "user_id"
Fixes #412
Refs #398
Keep the imperative mood in BREAKING CHANGE: too, so release notes read as a list of actions.
Why Bother
Three returns, in the order you actually notice them.
1. The answer is one command away. When something breaks six months later, git log --grep="^fix(auth)" hands you every change to authentication, in order, with reasons attached. No archaeology required.
2. Releases become a byproduct. Tools like standard-version, semantic-release, and Changesets read your commit types and generate the changelog and version bump for you. Writing changelogs by hand every release stops being a task.
3. Scope makes review cheaper. fix(api) and fix(ui) route to different people. Over time that prefix also becomes a map of your codebase. You can list every change to payments by reading a single grep.
"Code is read much more often than it is written." Guido van Rossum
Commit messages are read far more often than they are written. They are not comments about the code; they are the narrative that explains how the code arrived at its current shape.
Two Weeks From Now
You do not need to convert your whole history. Start with the next commit:
fixalone becomesfix(auth): stop refreshing tokens that are still validupdatebecomesfeat(profile): add the avatar upload field
Keep the subject under 50 characters. Add a body the moment the why is not obvious from the diff. That is the entire habit.
The next person looking for an answer in this repository, you included, will find it in seconds.
If your team has its own conventions, the Conventional Commits specification is worth twenty minutes. Anything that keeps the shape and fits your workflow will do.