Conventional Commits: A Practical Guide
A commit message format that enables automation. Learn the types, the scope, the breaking change marker, and the tooling it unlocks.
By Velloreth
The format
type(scope): description
body
footer
The subject line is type(scope): description.
The body is optional and explains the why.
The footer carries a reference or a breaking change note.
feat(auth): add password reset via email
The reset link expires after one hour and can be used once.
Closes #142
The types
| Type | Meaning | Version bump |
|---|---|---|
feat | a new feature | minor |
fix | a bug fix | patch |
docs | documentation | none |
style | formatting | none |
refactor | neither a feature nor a fix | none |
perf | a performance improvement | patch |
test | a test | none |
build | the build system | none |
ci | the pipeline | none |
chore | maintenance | none |
revert | a revert | patch |
The type drives the version bump. A feat is a minor, a fix is a patch, and a breaking change is a major.
The type also drives the changelog section. A tool groups the commits by type.
The scope
The scope names the area of the change.
feat(api): add pagination to the users endpoint
fix(ui): correct the button alignment on mobile
It is optional. A small project does not need it.
Keep it consistent. api, API and backend for the same area is worse than no scope.
Keep it short. One word is usually enough.
The description
Imperative mood. “add” not “added” or “adds”.
Why: the message completes the sentence “this commit will…”.
feat: add dark mode <- correct
feat: added dark mode <- wrong
feat: adds dark mode <- wrong
Lowercase after the colon. A convention, and a linter enforces it.
No period at the end. The subject is a title.
Under 72 characters. A longer subject is truncated in a terminal and in a git log.
What, not how. The body explains the how.
The body
The body explains the why.
fix(cache): invalidate the user key on profile update
The profile update wrote to the database but did not delete the
cache key, so a user saw the old name for up to an hour.
The fix deletes the key in the same transaction as the write.
Wrap at 72 characters. A long line is hard to read in a terminal.
Separate the body from the subject with a blank line. Git treats the first line as the subject.
The breaking change
Mark it with an exclamation mark.
feat!: remove the legacy /v1 API
And add a footer.
feat!: remove the legacy /v1 API
BREAKING CHANGE: the /v1 endpoints are removed. Clients must
migrate to /v2, which changes the response shape for the user
object. See the migration guide.
The footer is required for a tool to detect the change reliably.
A breaking change triggers a major version bump.
The footer
A reference to an issue.
Closes #142
Fixes #98
Refs #77
A co-author.
Co-authored-by: Name <email@example.com>
A breaking change note.
BREAKING CHANGE: ...
What it enables
An automatic changelog. A tool reads the commits since the last tag and groups them.
## 1.3.0
### Features
- add password reset via email (#142)
### Bug Fixes
- invalidate the user key on profile update (#98)
An automatic version bump. A feat is a minor, a fix is a patch, a breaking change is a major.
An automatic release. A tool tags the commit, publishes the changelog, and publishes the package.
A searchable history. git log --grep="^fix" finds every fix.
A review signal. A commit that is a refactor and a feat at once is a commit that should be split.
The tooling
commitlint validates the message.
// commitlint.config.js
export default {
extends: ['@commitlint/config-conventional'],
};
A commit-msg hook runs it.
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit "$1"'
commitizen prompts for the fields.
npx cz
semantic-release or release-please automates the version and the changelog.
A squash merge with a conventional title is a common way to keep the main history clean.
Adopting the convention in a team
A convention is only useful when the whole team follows it, and the adoption is the hard part. The first step is to add the linter to the pipeline, so a non-conforming message is caught before it is merged. The second is to add a commit template, so the format is visible when the editor opens. The third is to start with the types only, and to add the scope later, because a large change at once is abandoned. The fourth is to use the convention in the pull request title, which is what a squash merge uses. The fifth is to generate the changelog from the commits, because a visible benefit is what makes the convention stick. A team that adopts the format and sees an automatic changelog keeps it, and a team that adopts it as a rule without a benefit drops it within a month.
The subject line in detail
The subject is the part that is read most, so it deserves the most care. It should complete the sentence “this commit will…”, which is why the imperative mood is the convention: “add” rather than “added”. It should be lowercase after the colon, with no period at the end, because it is a title rather than a sentence. It should be under 72 characters, because a longer subject is truncated in a terminal and in a git log. It should name the change rather than the file, because the file is visible in the diff. And it should be specific: “fix the cache key on profile update” is useful, and “fix bug” is not. A reviewer who reads only the subject line should know what the commit does.
Common mistakes
A vague subject. “fix stuff” says nothing.
Past tense. “added” instead of “add”.
A period at the end. A convention, and a linter rejects it.
A subject over 72 characters. It is truncated.
A breaking change without the footer. A tool cannot detect it.
A commit that does two things. It should be split.
An inconsistent scope. Worse than no scope.
A chore for everything. The type loses its meaning.
No body for a non-obvious change. The why is lost.
A quotable summary
A conventional commit is type(scope): description, where the type is from a fixed set and drives the version bump and the changelog section. The description is imperative, lowercase and under 72 characters, the body explains the why, and a breaking change is marked with an exclamation mark and a BREAKING CHANGE footer. The format is machine-readable, which enables an automatic changelog, version bump and release.
Related reading
For the git side, see git-commit-messages-guide and git-rebase-vs-merge. For the broader context, semantic-versioning-explained and ci-cd-explained.