What is the Conventional Commits format?

Conventional Commits use the format type(scope): subject followed by an optional body and footer. Common types are feat, fix, docs, refactor, test, chore, perf, build, ci, and revert. The format makes commit history readable and enables automatic changelog and version generation.

How long should a commit message subject be?

Keep the subject line under 50 characters, with a hard cap at 72. Use the imperative mood (add, fix, update), do not end with a period, and separate it from the body with a blank line.

How do I mark a breaking change in a commit?

You can add an exclamation mark after the type and scope (feat(auth)!: subject) or add a BREAKING CHANGE: footer with a description. Both trigger a major version bump under semantic versioning.

How to Write a Commit Message

The Conventional Commits format, seven rules, real examples, and a free generator.

A good commit message answers two questions: what changed and why. The diff already shows how. This guide covers the Conventional Commits format, shows real examples, and links a free generator so you never start from a blank commit message again.

The Conventional Commits format

type(scope): subject

body

footer

type — what kind of change: feat, fix, docs, refactor, test, chore, perf, build, ci, revert
scope (optional) — the part of the codebase affected, e.g. auth, api, ui
subject — a short imperative summary (under 50 characters, lowercase, no trailing period)
body (optional) — explain what and why, wrapped at 72 characters
footer (optional) — breaking changes (BREAKING CHANGE:) and issue references (Closes #123)

The seven rules of a great commit message

Separate subject from body with a blank line.
Limit the subject line to 50 characters (hard cap 72).
Capitalize the subject line (or keep it lowercase for conventional commits — pick one and be consistent).
Do not end the subject line with a period.
Use the imperative mood in the subject ("add", "fix", "update" — not "added" or "fixes"). The message should complete the sentence "If applied, this commit will ___."
Wrap the body at 72 characters.
Use the body to explain what and why, not how.

Real examples

Feature

feat(auth): add rate limiting to the login endpoint

prevents brute-force attacks on user accounts
adds a 5-requests-per-minute limit per IP
returns 429 with a Retry-After header when exceeded

Closes #142

Bug fix

fix(parser): handle null values in nested config

the parser threw on null children of a config node;
now treats null as an empty object and continues

Breaking change

feat(auth)!: require CAPTCHA token on login

BREAKING CHANGE: the login endpoint now requires a
`captcha_token` field in the request body.

Small change (header only)

docs: clarify the API rate limit in the README

The type cheat sheet

Type	Use it when…
`feat`	you add a new feature for the user
`fix`	you patch a bug
`docs`	documentation only (README, comments)
`style`	formatting, whitespace (no logic change)
`refactor`	restructure code without changing behavior
`perf`	improve performance
`test`	add or fix tests
`build`	build system or dependencies
`ci`	CI pipeline configuration
`chore`	tooling, config, misc
`revert`	revert a prior commit

Why it matters

Conventional commits aren't just style. They let tooling auto-generate changelogs, auto-bump semantic versions (feat: → minor, fix: → patch, !/BREAKING CHANGE: → major), and make a large codebase's history greppable: git log --grep "^fix(" finds every bug fix.

Free Commit Message Generator

Don't want to format it by hand? Our free generator turns a plain-English description of your change into four clean variants — standard Conventional Commit, breaking-change shorthand, a minimal header, and a gitmoji-styled version. No signup, no cost.

Open the Commit Message Generator →

More free developer tools

Changelog Generator — turn changes into a Keep-a-Changelog entry
README Intro Generator — write the opening of a README
Launch Tweet Generator — 3 tweet variants from product details
Show HN Title Checker — score your HN title