Conventional commits cheat sheet (with real examples)

Conventional commits is a small format that makes Git history readable, enables automated changelog tools, and signals to senior engineers that you know what you're doing. Bookmark this page — you'll come back to it.

The format in one line

<type>(<optional scope>): <short description>

[optional body]

[optional footer]

Examples:

feat: add password reset flow
fix(auth): use env secret instead of hardcoded JWT key
chore(deps): upgrade React to 18.3
docs: clarify env var setup in README
refactor(api): extract user-fetching into a helper
test: add coverage for null-email case

That's the whole format. The next section is the cheat sheet of types.

The complete type reference

The hard part: choosing between feat, fix, chore, and refactor

Most beginners get tangled here. The decision tree:

• Did the user-visible behavior change? If yes, it's feat (added something) or fix (corrected something broken).
• Did internal code change but behavior is identical? It's refactor.
• Did nothing in the application change but config/tooling did? It's chore or build or ci.

Examples of the same change with different correct types:

• feat: add dark mode toggle — user can now toggle dark mode (new behavior).
• fix: dark mode toggle doesn't persist across reloads — existing feature was broken.
• refactor: extract dark mode logic into useTheme hook — same behavior, cleaner code.
• chore: rename dark-mode files to lowercase — neither user nor code logic changed.

The optional scope

Scope tells reviewers where the change happened. It's optional but useful in larger codebases:

feat(auth): add password reset flow
fix(api): return 400 instead of 500 on null email
chore(deps): upgrade React to 18.3
docs(readme): document env var setup

Common scopes: auth, api, ui, db, deps, the name of a specific module. Whatever your team uses. Don't invent new scopes — match what's in the repo's history.

Breaking changes

If your change breaks backward compatibility, mark it with ! after the type:

feat!: rename `userId` to `user_id` in API responses

BREAKING CHANGE: All API consumers must update field name.

The ! tells everyone "this will require coordinating with consumers." The BREAKING CHANGE: footer gives details. Don't sneak breaking changes into fix or refactor commits — your downstream consumers will hate you.

The body (when to add one)

Most commits don't need a body. Add one when:

• The why isn't obvious from the description
• You made a non-obvious tradeoff
• You want to reference a ticket or issue

fix: cache user lookups for 5 minutes

We were making a DB query on every request, which was fine
at 10 req/s but starting to show in p99 latency at 200 req/s.

Five minutes was chosen because user role changes are rare
and the existing /users PATCH already invalidates the cache.

Closes IQ-142.

Real-world commit examples (good vs. bad)

Bad commits, and why

• "updates" — describes nothing
• "WIP" — should never reach main; squash before merging
• "fixed bug" — which bug? In what file? What was the fix?
• "updated user.py" — describes the file, not the change
• "feat: lots of changes to auth and api and ui" — too broad; split into multiple commits
• "fix: typo" — okay if it's literally a typo, but in commit messages a scope helps: fix(readme): typo in install command

Good commits, and why

• fix(auth): return 401 instead of 500 on expired token — clear scope, clear before/after
• feat: add dark mode toggle to settings page — what was added, where
• chore(deps): upgrade React from 18.2 to 18.3 — exact versions, easy to grep later
• refactor(api): extract retry logic into withRetry helper — what moved, into what
• perf(db): add index on users.email — what was changed, what it affects

Why bother with all this

Three concrete reasons, in order of how much you'll feel them:

1. Senior engineers will respect you instantly. A clean commit history signals that you understand professional norms. It's a 30-second cost that pays back forever.
2. Automated tools work. Tools like standard-version, semantic-release, and changesets read your commits to auto-generate changelogs and bump versions. You don't have to write release notes — they write themselves.
3. Future-you can debug faster. Six months from now, you'll git log --grep="auth" looking for when a bug was introduced. With conventional commits, you find it in 10 seconds. Without, you read a thousand lines of "updates" and "wip" and want to quit.

The two-line rule

1. Subject line under 72 characters, lowercase, no period.
2. If you need a body, leave one blank line, then write it. Wrap at 72 characters.

That's it. You now know more about commit messages than most third-year engineers.