Message format

Introduction

Conventional Commits is a commit message convention that maps commits to SemVer releases.

This reference covers the message grammar, the recommended types, breaking-change markers, and the tooling that reads them.

Anatomy

<type>(<scope>)!: <description>

[optional body]

[optional footer(s)]

Fields

PartRequiredNotes
typeyesnoun such as feat or fix
scopenocodebase section, inside ()
!nobreaking change marker, before :
descriptionyesshort summary after :
bodynofree-form, after one blank line
footersnotoken/value pairs after the body

The colon and space after the prefix are required, so feat:add does not parse. The ! sits immediately before the colon.

See: Specification summary

Types

TypeSignalsSemver
featadds a featureMINOR
fixpatches a bugPATCH
docsdocumentation onlynone
styleformatting, no code changenone
refactorneither fix nor featurenone
perffaster codenone
testtests added or fixednone
buildbuild system or depsnone
ciCI config and scriptsnone
choreother changes outside src and testsnone
revertundoes an earlier commitnone

Only feat and fix have spec-defined meanings. The rest are the @commitlint/config-conventional set; additional types are allowed, but they carry no semver meaning unless marked breaking.

See: config-conventional

Scopes

feat(lang): add Polish language
fix(parser): handle empty input
docs(api): document the retry option

A scope names the section of the codebase: a package, module, or route. Parentheses are required. Parsers treat type and scope as case-insensitive, so pick one casing and keep it.

See: Specification

Body and footers

fix: prevent racing of requests

Dismiss responses that are not from the latest request.

Reviewed-by: Z
Refs: #123
Closes #124
FooterSignals
Refs: #123related issue or commit
Closes #123closes the issue on merge
Reviewed-by: Zreviewer trailer
BREAKING CHANGE: …breaking change, uppercase

Body and footers each start after one blank line. Tokens replace spaces with -, except BREAKING CHANGE; a value may span lines until the next token. BREAKING-CHANGE is a synonym.

See: git interpret-trailers

Breaking changes

FormExample
! before :feat!: drop Node 6 support
FooterBREAKING CHANGE: drop Node 6 support
Bothfeat(api)!: drop Node 6 plus a footer

The footer form is uppercase and works with any type. With ! alone, the description must describe the break. Both forms may appear together.

See: Specification

Writing commits

Multi-paragraph messages

fix: prevent racing of requests

Introduce a request id and a reference to the latest
request. Dismiss incoming responses other than the
latest.

Remove timeouts used to mitigate the racing issue.

Reviewed-by: Z
Refs: #123

One flag per paragraph

git commit \
  -m 'fix: prevent racing of requests' \
  -m 'Dismiss stale responses by request id.' \
  -m 'Reviewed-by: Z'

Each -m becomes a paragraph, separated by a blank line, so a body and footers fit without an editor.

See: Examples

Reverts

revert: let us never again speak of the noodle incident

Refs: 676104e, a215868

The spec leaves revert handling to tooling, and recommends this shape: a revert type plus a footer naming the reverted SHAs. git revert writes Revert "...", which does not parse, so reword the subject.

See: Revert commits

Merge and squash commits

# Squash: the commit subject is the PR title
git merge --squash feature/login
git commit -m 'feat(auth): add login with SSO'
# Merge commit: pass a conventional subject
git merge --no-ff feature/login -m 'feat(auth): add SSO'

A squash leaves one commit, so the PR title carries the type. Plain merge commits do not parse, and tools skip them. Contributors can commit freely when a maintainer edits the squash message.

See: Contributor workflow

Versioning

Semver

Each commit maps to a release bump, and tools pick the highest one since the last tag.

See: Semantic Versioning

Mapping to semver

Commits since last releaseBumpExample
fix: onlyPATCH1.2.3 → 1.2.4
any feat:, no breakMINOR1.2.3 → 1.3.0
! or BREAKING CHANGE:MAJOR1.2.3 → 2.0.0

The highest bump wins, so a breaking fix: is still a major release. Breaking changes count whatever the commit type.

See: Conventional Commits and SemVer

Release tools

ToolCommandBehaviour
semantic-releasenpx semantic-releasetags and publishes
standard-versionnpx standard-versionbumps files, writes changelog
commit-and-tag-versionnpx commit-and-tag-versionmaintained fork of standard-version

semantic-release runs on the release branch after CI. standard-version is deprecated: its README recommends release-please, while the fork keeps the same local workflow.

See: semantic-release docs

Parsing with git log

# Subjects since the last tag
git log --no-merges --format='%s' v1.2.0..HEAD
# Count each type
git log --no-merges --format='%s' v1.2.0..HEAD |
  sed -nE 's/^([a-zA-Z]+)(\([^)]*\))?!?: .+/\1/p' |
  sort | uniq -c | sort -rn

Replace the range with your last tag. The expression drops the scope and ! and skips subjects that do not parse, so the output is a count per type.

See: git log

Tooling

commitlint

commitlint.config.js

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'scope-enum': [2, 'always', ['api', 'cli', 'web']]
  }
}

Husky hook

pnpm add -D @commitlint/cli @commitlint/config-conventional husky
pnpm exec husky init
echo 'npx --no -- commitlint --edit "$1"' > .husky/commit-msg

The hook checks the message file before the commit lands. Lint the same range in CI with npx commitlint --from origin/master --to HEAD.

See: Local setup

Commitizen

pnpm add -D commitizen
pnpm exec commitizen init cz-conventional-changelog \
  --pnpm --save-dev --save-exact
pnpm exec cz

cz prompts for the parts and writes the message, so contributors do not need the grammar memorised.

See: cz-cli

0 Comments for this cheatsheet. Write yours!