We use cookies to understand how the site is used and to display ads. Analytics and advertising only run after you accept. You can change your choice anytime. Privacy policy

Skip to content
devvkit
$devvkit resources --cheatsheet conventional-commits-cheatsheet

Conventional Commits Cheatsheet

[version-control]

Every pattern of the Conventional Commits spec: types, scopes, breaking changes, footers, semantic versioning, and tools, with syntax and real use cases.64 commands · 7 sections

Conventional Commits is a lightweight commit-message convention that drives semantic versioning, automatic changelogs, and clean history. This cheatsheet covers the format, every commit type, scopes, breaking changes, footers, and the tools that enforce it.

The format is simple: type(scope): description: followed by an optional body and footer.

The Format11

$type(scope): description
Use case: The core format: type, optional scope, and a description after a colon.Example: feat(auth): add password reset flow
$feat: description
Use case: The two most common commits: feat for new functionality.Example: feat: add dark mode toggle
$fix: description
Use case: fix for bug fixes.Example: fix: handle empty payload in API client
$type(scope): description Body line
Use case: A blank line starts the body: WHY you made the change.Example: fix: retry on 429 Third-party rate limits were hit during bursts; add backoff.
$type: description FOOTER: value
Use case: Footers after the body: BREAKING CHANGE, Ref, Co-authored-by.Example: feat: remove legacy endpoint BREAKING CHANGE: /v1/users is removed
$type: description (#123)
Use case: Convention for referencing PRs: popular on GitHub.Example: fix: sidebar overflow (#452)
$type!: description
Use case: The ! marks a breaking change: no footer needed.Example: feat!: switch to ES modules
$revert: type: description
Use case: Reverting a previous commit: the revert prefix.Example: revert: feat: add dark mode toggle
$ci: / chore: / build:
Use case: Tooling commits: CI config, chores, build system (not shipped features).Example: ci: pin node to 22.x
$docs: / refactor: / perf: / test:
Use case: Docs, refactors, performance, and tests: no behavior change.Example: test: cover retry logic
$style: description
Use case: Formatting only: no logic change (spacing, semicolons).Example: style: run prettier on src

Commit Types12

$feat: add / new / support
Use case: A NEW feature for the user: bumps MINOR version.Example: feat: add CSV export
$fix: fix / correct / handle
Use case: A bug fix: bumps PATCH version.Example: fix: correct timezone parsing
$docs: document / update docs / clarify
Use case: Documentation only: no version bump.Example: docs: clarify setup steps
$refactor: extract / rename / simplify
Use case: Internal restructuring: no behavior change.Example: refactor: extract retry helper
$perf: optimize / speed up / reduce
Use case: Performance improvement: faster or lighter.Example: perf: memoize expensive selector
$test: add tests / fix tests
Use case: Test code: new tests or fixes to existing ones.Example: test: cover pagination edge cases
$build: bump / configure build
Use case: Build system changes: bundlers, compilers, versions.Example: build: bump typescript to 5.6
$ci: add workflow / update pipeline
Use case: CI/CD configuration changes.Example: ci: add nightly regression run
$chore: update deps / housekeeping
Use case: Maintenance that fits nothing else.Example: chore: update lockfile
$style: format / lint fix
Use case: Whitespace, formatting, lint: no logic change.Example: style: remove trailing commas
$perf + fix / feat + fix (split)
Use case: One concern per commit: split mixed changes into multiple commits.Example: perf: cache lookups fix: correct cache key
$refactor(full rewrite): ...
Use case: Scopes name the AREA: component, module, or package.Example: refactor(router): rewrite matching

Scopes & Breaking Changes8

$feat(api): ...
Use case: Scope names the affected area: api, cli, core, ui.Example: feat(api): add pagination param
$fix(router): ...
Use case: Scope the fix to its module: history stays navigable.Example: fix(router): reload on param change
$feat(auth)!: ...
Use case: Breaking change in a scoped feature: the ! suffix.Example: feat(auth)!: require 2FA by default
$feat: ... BREAKING CHANGE: ...
Use case: The footer form: explain WHAT broke and HOW to migrate.Example: feat: switch to v2 auth BREAKING CHANGE: access tokens must now be JWT
$BREAKING-CHANGE: ...
Use case: Alternative footer spelling: both are parsed.Example: BREAKING-CHANGE: removed /v1 endpoints
$fix!: ...
Use case: Even a fix can be breaking: if the behavior change is incompatible.Example: fix!: drop Node 18 support
$refactor(types)!: ...
Use case: Breaking refactors: type and interface changes.Example: refactor(types)!: rename UserPayload to UserDto
$chore(deps)!: ...
Use case: Breaking dependency upgrades: major version bumps.Example: chore(deps)!: upgrade react to 19

Examples11

$feat(ui): add tooltip component
Use case: New UI feature: scoped to the ui area.Example: feat(ui): add tooltip component
$fix(api): return 404 for missing users
Use case: Bug fix in the API: precise scope and outcome.Example: fix(api): return 404 for missing users
$perf(db): index the email column
Use case: Performance work scoped to the database layer.Example: perf(db): index the email column
$docs: add deployment guide
Use case: Documentation addition.Example: docs: add deployment guide
$test: add e2e for checkout flow
Use case: Test additions.Example: test: add e2e for checkout flow
$build: add esbuild bundle step
Use case: Build configuration change.Example: build: add esbuild bundle step
$ci: cache node_modules in workflow
Use case: CI pipeline optimization.Example: ci: cache node_modules in workflow
$refactor: extract auth middleware
Use case: Internal cleanup without behavior change.Example: refactor: extract auth middleware
$style: sort imports
Use case: Formatting-only change.Example: style: sort imports
$feat(cli)!: rename --prod to --production
Use case: Breaking CLI change: flag renamed.Example: feat(cli)!: rename --prod to --production
$fix: validate webhook signature Prevents forged events. Closes #88.
Use case: Full commit: subject, body, and issue reference.Example: fix: validate webhook signature Prevents forged events. Closes #88.

Semantic Versioning8

$MAJOR.MINOR.PATCH
Use case: The version scheme: 1.4.2 = major.minor.patch.Example: 1.4.2
$BREAKING CHANGE → MAJOR
Use case: Breaking changes bump the major version: 1.4.2 → 2.0.0.Example: feat! → 2.0.0
$feat → MINOR
Use case: New features bump minor: 1.4.2 → 1.5.0.Example: feat: add export → 1.5.0
$fix → PATCH
Use case: Bug fixes bump patch: 1.4.2 → 1.4.3.Example: fix: crash on empty input → 1.4.3
$1.5.0-beta.1
Use case: Pre-release identifiers: before the stable release.Example: 1.5.0-beta.1
$^1.4.0 / ~1.4.0
Use case: Ranges: ^ allows minor+patch, ~ allows patch only.Example: npm i express@^5.0.0
$semantic-release
Use case: The tool that derives versions from commit types automatically.Example: npx semantic-release
$docs/chore/test → no bump
Use case: Non-shipped changes never bump the version.Example: docs: fix typo → still 1.4.2

Changelog & Releases6

$semantic-release generates CHANGELOG.md
Use case: Changelog sections come from commit types: Features, Fixes, BREAKING CHANGES.Example: # Features - add dark mode # Fixes - correct timezone
$conventional-changelog -p angular -i CHANGELOG.md -s
Use case: Generate a changelog from git history (Angular preset).Example: npx conventional-changelog-cli -p angular -i CHANGELOG.md -s
$git log --oneline --grep="^feat"
Use case: List feature commits since a release: draft release notes.Example: git log v1.0.0..HEAD --oneline --grep="^feat"
$git log v1.0.0..HEAD --oneline --grep="BREAKING"
Use case: Collect breaking changes for the release notes.Example: git log v1.0.0..HEAD --oneline --grep="BREAKING"
$git tag v2.0.0 && git push --tags
Use case: Tag the release after the version bump: semantic-release does this for you.Example: git tag v2.0.0 git push --tags
$git log --format="%s" v1.0.0..HEAD | grep -E "^(feat|fix)"
Use case: Plain-text release summary from commit subjects.Example: git log --format="%s" v1.0.0..HEAD | grep -E "^(feat|fix)"

Enforcement & Tools8

$commitlint
Use case: Lint commit messages: reject non-conforming formats.Example: echo "feat: x" | npx commitlint
$commitlint config: "@commitlint/config-conventional"
Use case: The standard rule set: type, empty-scope, subject-case rules.Example: "commitlint": { "extends": ["@commitlint/config-conventional"] }
$husky pre-commit hook
Use case: Run commitlint before every commit: catches mistakes locally.Example: .husky/pre-commit: npx commitlint --edit $1
$commitizen
Use case: Interactive commit composer: picks types for you.Example: npx cz
$semantic-release + GitHub Actions
Use case: Automate release: analyze commits, bump version, publish, write changelog.Example: jobs: release: steps: - run: npx semantic-release
$semantic-release --dry-run
Use case: Preview what would be released: no side effects.Example: npx semantic-release --dry-run
$release-please (Google)
Use case: Alternative release automation: PR-based version bumps.Example: npx release-please release-pr
$git commit -m "feat: ..." (atomic)
Use case: One concern per commit: small, reviewable history.Example: git commit -m "fix: retry on 429"

Frequently asked questions

What is a conventional commit?

A commit message format with a structured prefix: type(scope): description, for example feat(api): add rate limiting. Types include feat, fix, docs, style, refactor, test, and chore, which drive automatic versioning and changelogs.

When should I use a breaking change?

Use the ! marker or BREAKING CHANGE footer when your commit requires consumers to change their code or configuration. Semantic-release then bumps the major version automatically instead of minor or patch.

Which tools enforce conventional commits?

commitlint validates messages in CI, husky runs it as a pre-commit hook, and semantic-release derives versions and changelogs from commit types. They work together to keep history consistent.