Conventional Commits: Types, Rules and Cheat Sheet
November 11, 2026 · 11 min read
Conventional Commits: Format, Types and a Cheat Sheet
Conventional Commits is a lightweight specification for commit messages. Each subject starts with a type such as feat or fix, an optional scope and a short description. Version 1.0.0 defines just two types plus a breaking-change marker, and release tools turn them into changelogs and version bumps. Below are the rules, the types and a copyable cheat sheet.
What Are Conventional Commits?
The official specification is a set of git commit message conventions that people and scripts can both read. A subject like fix(parser): handle empty input tells a reviewer what changed. It also tells a release script that this change is a patch.
You'll also see the same idea called semantic commit messages, an informal name rather than a separate spec. It grew out of the Angular commit guidelines, and the current version is 1.0.0.
Teams adopt it for three practical reasons. Changelogs can be generated from history, the next version number can be picked from the commit types, and git log --oneline becomes something you can scan in seconds. The spec doesn't cover writing style, so subject length and tone stay your team's call. For those, our git commit message guide covers the 50/72 rule and imperative mood.
What Are the Rules of the Conventional Commits Specification?
Every conventional commit message follows this shape:
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
The square brackets mark optional parts, and you don't type them. The spec has 16 numbered rules, which boil down to these:
- The subject starts with a type, an optional scope in parentheses, an optional
!, then a colon and a space. featmust be used for a new feature.fixmust be used for a bug fix.- A scope is a noun that names a part of the codebase, as in
fix(parser):. - The description comes straight after the colon and space. It's a short summary of the change.
- An optional body starts one blank line after the description. It can hold any number of paragraphs.
- Footers start one blank line after the body. Each one is a token, a separator (colon plus space, or space plus
#) and a value. - Footer tokens use hyphens instead of spaces, like
Reviewed-by. The only exception isBREAKING CHANGE. - A breaking change is marked with
!right before the colon, with aBREAKING CHANGE:footer, or both. - Tools must treat every part as case-insensitive, except
BREAKING CHANGE, which must be uppercase. BREAKING-CHANGEmeans exactly the same asBREAKING CHANGEwhen used as a footer token.
That's the whole contract, and the footer format is modelled on git trailers. Most of the type list you've seen in tutorials is convention layered on top.
Conventional Commits Types: Which Are Required and Which Are Convention?
Only feat and fix have a defined meaning in the spec. Any other type is allowed. The spec points to @commitlint/config-conventional, which is based on the Angular convention, as one source of extra types. Its list is the one most teams copy:
build: the build system or external dependencies (npm, gulp)chore: other changes that don't touch source or test filesci: CI configuration files and scriptsdocs: documentation onlyperf: a code change that improves performancerefactor: a code change that neither fixes a bug nor adds a featurerevert: undoing a previous commitstyle: whitespace, formatting or missing semicolons, with no change in meaningtest: adding missing tests or correcting existing ones
None of these nine types carries a version meaning in the spec. Release tools can add their own rules, though. semantic-release's default rules, for example, publish a patch for perf commits.
We prefer a short, agreed list written into your CONTRIBUTING.md over people inventing a new type per commit. Nine types are plenty, and chore shouldn't become a bin for everything. Our Markdown templates include a CONTRIBUTING skeleton where that list fits. The README guide covers where contributor rules belong in a repository.
How Do You Mark a Breaking Change?
Any type can carry a breaking change. You mark it in the subject line, in a footer, or in both places.
feat(api)!: remove the v1 endpoints
The ! sits immediately before the colon, after the scope. Writing feat!(api): breaks the spec's prefix order, so parsers that follow it won't recognise the header. With no footer, the spec says the description doubles as the breaking-change note, which here is "remove the v1 endpoints".
refactor: drop support for Node 18
BREAKING CHANGE: the package now needs Node 20 or later.
This subject looks routine, but the footer flags a major release. The token must be uppercase and followed by a colon and a space.
feat(config)!: read settings from config.toml
BREAKING-CHANGE: settings.json is no longer loaded. Convert it to TOML.
Using both markers is the clearest option for reviewers, because the ! shows up in one-line logs and the footer explains the migration. The hyphenated BREAKING-CHANGE token is an exact synonym.
One mistake to avoid: don't start the subject line itself with BREAKING CHANGE:. That text belongs in the footer. As a subject it has no valid type, so tools based on the spec miss the commit and commitlint rejects it.
Scopes, Bodies and Footers in Real Commit Messages
A scope narrows the type to one area of your codebase. Keep scopes to nouns your team already uses, such as package or module names.
fix(auth): refresh expired tokens before retrying
The client retried with the stale token and failed twice before
logging the user out. It now refreshes first and retries once.
Refs: #482
Reviewed-by: Priya Shah
This is a patch-level fix in the auth area. The body explains why, and both closing lines parse as footers because each has a one-word or hyphenated token followed by a colon and a space.
docs: correct the install steps for Windows
Closes #77
The space-plus-hash separator is valid too, so Closes #77 is a footer with the token Closes and the value 77.
Standard git trailers such as Co-authored-by and Signed-off-by also count as valid footers, so adding them won't trip up a Conventional Commits parser.
How Commit Types Map to Version Bumps
The spec ties three markers to Semantic Versioning. Tools that compute versions from history generally apply the highest bump found since the last release.
| Commit | Version effect | Starting from 1.4.2 |
|---|---|---|
fix: | PATCH | 1.4.3 |
feat: | MINOR | 1.5.0 |
Any type with ! or a BREAKING CHANGE footer | MAJOR | 2.0.0 |
docs, chore, ci and every other type | None on its own | 1.4.2 |
How MAJOR, MINOR and PATCH work, including the special rules for 0.x versions, is defined by SemVer itself rather than by this spec. Our semantic versioning guide walks through those rules with examples.
The same types also sort entries into release notes. Paste your conventional-commit lines, for example the output of git log --oneline, into our changelog generator. It drafts Keep a Changelog Markdown or GitHub-style release notes in your browser. Nothing is pulled from your repository, so the input is only the text you paste. The annotated changelog example shows a finished file and compares it with a draft generated from commits like these.
How to Enforce Conventional Commits in Git and on GitHub
The spec says nothing about enforcement, so you add it with tooling. The usual choice is commitlint with its conventional config, run from a commit-msg Git hook. These are the npm and husky v9 commands for Linux and macOS from commitlint's own guides:
npm install -D @commitlint/cli @commitlint/config-conventional
echo "export default { extends: ['@commitlint/config-conventional'] };" > commitlint.config.js
npm install --save-dev husky
npx husky init
echo "npx --no -- commitlint --edit \$1" > .husky/commit-msg
The husky init command also creates a sample pre-commit hook, so edit or delete it if you don't want it. After that, a message like Added stuff fails before the commit is created, with errors saying the type and subject are empty. The conventional config is stricter than the spec. It requires lowercase types, caps the header at 100 characters and rejects subjects written in sentence case or upper case.
Conventional Commits on GitHub has one extra wrinkle: squash merging. By default, the squash commit takes the commit title for a one-commit pull request, or the PR title when there are two or more commits. You can change the default squash message to always use the PR title, then lint that title in CI:
- name: Lint PR title
env:
PR_TITLE: ${{ github.event.pull_request.title }}
run: echo "$PR_TITLE" | npx commitlint
This step assumes the job has already checked out the repository and installed commitlint. One limitation applies to every setup: linting checks format, not truth. commitlint can't tell that your fix actually ships a new feature, so code review still has to catch the wrong type.
Conventional Commits Cheat Sheet
Copy this table into your CONTRIBUTING.md and trim it to the types your team uses.
| Type | Use it for | Version effect | Example subject |
|---|---|---|---|
feat | A new feature | MINOR | feat(cart): add saved carts |
fix | A bug fix | PATCH | fix(auth): refresh expired tokens |
docs | Documentation only | None | docs: add Windows install steps |
style | Formatting with no change in meaning | None | style: run prettier on src |
refactor | Restructuring with no new feature or fix | None | refactor(db): extract query builder |
perf | A performance improvement | None in the spec, PATCH in some tools | perf(search): cache index lookups |
test | Adding or correcting tests | None | test(api): cover 404 responses |
build | Build system or dependencies | None | build(deps): bump lodash |
ci | CI configuration and scripts | None | ci: run tests on pull requests |
chore | Upkeep outside source and test files | None | chore: update .gitignore |
revert | Undoing an earlier commit | Depends on your tool | revert: restore old checkout flow |
Any type plus ! or a footer | An incompatible change | MAJOR | feat(api)!: remove v1 endpoints |
Three edge cases come up often:
- A commit fits two types. Split it into two commits. The spec's FAQ recommends this whenever possible.
- You used the wrong type. Before merging or releasing, rewrite it with
git rebase -i, as the spec suggests. After a release, the cleanup depends on your release tooling. - You're reverting. The spec leaves revert handling to tool authors. Its suggestion is a
revert:type plus aRefs:footer listing the reverted SHAs.
revert: restore the old checkout flow
Refs: 3f9c2e1, a07b5d4
Questions About Commit Types, Casing and History
Conventional Commits asks for very little: a type, an optional scope, a description and a clear breaking-change marker. Agree on your type list, write it into CONTRIBUTING.md and let a hook catch the typos. For conventions inside the Markdown files themselves, see our Markdown style guide. You can draft that CONTRIBUTING section in the free online editor, with a live preview beside your text, without creating an account.