Writing

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.

TypeUse it forExample
featA new feature visible to usersfeat(auth): add passkey sign-in
fixA bug fixfix(cart): correct total when a coupon applies
docsDocumentation onlydocs: update the local setup guide
styleFormatting, no logic changestyle: normalise indentation in the css files
refactorCode restructured, behaviour unchangedrefactor(user): simplify validation logic
perfA change made for speedperf(query): index the incident lookup
testAdding or changing teststest: cover empty cart totals
choreMaintenance with no source changechore(deps): bump laravel to 13
buildBuild system or dependenciesbuild: switch bundler to turbopack
ciContinuous integration configurationci: run migrations before e2e

Two rules keep this honest:

  • fix needs a real reproduction. A fix commit means something was broken and now it is not. Refactoring that happens to touch the same line is a refactor.
  • style and chore never touch behaviour. If a reviewer has to ask "does this change what ships?", it is not a style commit.

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:

  • fix alone becomes fix(auth): stop refreshing tokens that are still valid
  • update becomes feat(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.