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:

  1. The subject starts with a type, an optional scope in parentheses, an optional !, then a colon and a space.
  2. feat must be used for a new feature. fix must be used for a bug fix.
  3. A scope is a noun that names a part of the codebase, as in fix(parser):.
  4. The description comes straight after the colon and space. It's a short summary of the change.
  5. An optional body starts one blank line after the description. It can hold any number of paragraphs.
  6. Footers start one blank line after the body. Each one is a token, a separator (colon plus space, or space plus #) and a value.
  7. Footer tokens use hyphens instead of spaces, like Reviewed-by. The only exception is BREAKING CHANGE.
  8. A breaking change is marked with ! right before the colon, with a BREAKING CHANGE: footer, or both.
  9. Tools must treat every part as case-insensitive, except BREAKING CHANGE, which must be uppercase.
  10. BREAKING-CHANGE means exactly the same as BREAKING CHANGE when 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 files
  • ci: CI configuration files and scripts
  • docs: documentation only
  • perf: a code change that improves performance
  • refactor: a code change that neither fixes a bug nor adds a feature
  • revert: undoing a previous commit
  • style: whitespace, formatting or missing semicolons, with no change in meaning
  • test: 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.

CommitVersion effectStarting from 1.4.2
fix:PATCH1.4.3
feat:MINOR1.5.0
Any type with ! or a BREAKING CHANGE footerMAJOR2.0.0
docs, chore, ci and every other typeNone on its own1.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.

TypeUse it forVersion effectExample subject
featA new featureMINORfeat(cart): add saved carts
fixA bug fixPATCHfix(auth): refresh expired tokens
docsDocumentation onlyNonedocs: add Windows install steps
styleFormatting with no change in meaningNonestyle: run prettier on src
refactorRestructuring with no new feature or fixNonerefactor(db): extract query builder
perfA performance improvementNone in the spec, PATCH in some toolsperf(search): cache index lookups
testAdding or correcting testsNonetest(api): cover 404 responses
buildBuild system or dependenciesNonebuild(deps): bump lodash
ciCI configuration and scriptsNoneci: run tests on pull requests
choreUpkeep outside source and test filesNonechore: update .gitignore
revertUndoing an earlier commitDepends on your toolrevert: restore old checkout flow
Any type plus ! or a footerAn incompatible changeMAJORfeat(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 a Refs: 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.