Conventional Commits: The Complete Guide to Structured Commit Messages

What Are Conventional Commits?

The Conventional Commits 1.0 specification defines a standard format for commit messages. A compliant commit looks like this:

feat(auth): add JWT token refresh mechanism

Implements automatic token refresh 5 minutes before expiry using
a refresh token stored in an httpOnly cookie. Falls back to full
re-login if the refresh token is also expired.

BREAKING CHANGE: The /auth endpoint now returns a refreshToken
field in addition to the access token.

Closes #142

The Commit Structure

Type (required): feat, fix, docs, style, refactor, perf, test, chore, ci, build. feat: triggers a MINOR version bump. fix: triggers a PATCH bump.
Scope (optional): The module or component affected — auth, parser, ui.
Description (required): Concise summary in imperative mood ("add" not "added" or "adds"). Max 72 chars recommended.
Body (optional): Detailed explanation of what changed and why. Wrap at 72 characters.
Footer (optional): Breaking changes (BREAKING CHANGE: — triggers MAJOR bump), issue references (Closes #142), or co-author credit.

Why It Matters

Automated versioning: Tools like semantic-release read commit types to determine the next version number — no human decides whether it's a minor or patch bump.
Auto-generated changelogs: A changelog tool extracts feat and fix commits into categorized release notes.
Git history as documentation: Every commit answers "what changed and why" — the history becomes the definitive record, not just a log of saved work.
Commit linting: commitlint enforces the format in CI, catching sloppy messages before they hit the main branch.

Common Commit Types

feat: A new feature. MINOR version bump.
fix: A bug fix. PATCH version bump.
docs: Documentation only changes. No version bump.
style: Formatting, missing semicolons, etc. — no code change. No version bump.
refactor: Code change that neither fixes a bug nor adds a feature. No version bump.
perf: A code change that improves performance. PATCH version bump.
test: Adding or correcting tests. No version bump.
chore: Maintenance tasks — updating deps, config changes. No version bump.
ci: CI/CD configuration changes. No version bump.

Generate Conventional Commits Instantly

Use ToolsVito's Conventional Commit Generator to build properly structured commit messages with type, scope, description, body, and footer. Follows the Conventional Commits 1.0 spec. All in your browser.