Conventional Commits: A Complete Guide for Development Teams

Everything you need to know about Conventional Commits — the standard format for git commit messages adopted by thousands of teams. Includes all types, examples, tooling, and automation.

Conventional Commits is a specification for adding human and machine readable meaning to commit messages. It's simple, widely adopted, and solves the real problem of inconsistent commit history that makes code archaeology painful.

If your team hasn't adopted a commit message standard yet, Conventional Commits is the right choice. It's supported by tooling across every major language ecosystem, it's the format expected by most CI/CD systems that auto-generate changelogs, and it's what most open source projects use.

The Conventional Commits Specification

The full format is:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

The type and description are required. Everything else is optional. The colon and space after the type are part of the format — don't skip them.

All Commit Types — With When to Use Each

feat — New Feature

Use for any commit that introduces a new feature or capability that didn't exist before. Maps to MINOR in Semantic Versioning.

feat(auth): add Google OAuth login
feat(api): add pagination to /users endpoint
feat: support dark mode in dashboard

fix — Bug Fix

Use for commits that fix a bug in existing functionality. Maps to PATCH in Semantic Versioning.

fix(auth): clear refresh token on logout
fix(api): handle null response from /users
fix: prevent double-submit on checkout form

docs — Documentation

Changes to documentation only — README, code comments, API docs. No code behavior changes.

docs(readme): add installation instructions for Windows
docs(api): document rate limiting headers
docs: fix typo in contributing guide

style — Code Style

Formatting changes that don't affect behavior — whitespace, semicolons, line length. Running prettier counts as style.

style: run prettier on all TypeScript files
style(components): fix inconsistent semicolons

refactor — Code Restructure

Code changes that neither fix a bug nor add a feature. Extracting a function, renaming a variable, reorganizing file structure.

refactor(auth): extract token validation into separate module
refactor: move database config to environment module
refactor(api): simplify error handling middleware

test — Tests

Adding missing tests, correcting existing tests, or refactoring tests. No production code changes.

test(auth): add unit tests for token refresh flow
test: increase coverage for API error handlers

chore — Maintenance

Changes to build process, auxiliary tools, dependency updates. Doesn't modify src or test files.

chore(deps): upgrade React to 18.3.0
chore: add .editorconfig
chore(ci): update Node.js version to 20 in GitHub Actions

perf — Performance

Changes that improve performance without changing behavior.

perf(db): add index on users.email for faster lookups
perf(api): implement response caching for /products

Using Scopes Effectively

The scope is a noun in parentheses describing the section of the codebase affected. It's optional but adds significant clarity in larger codebases.

Good scopes are:

• Module names: feat(auth):, fix(api):, refactor(db):
• Component names: style(Button):, feat(NavBar):
• Package names in monorepos: feat(web-app):, fix(shared-ui):

Avoid overly specific scopes that don't add value: fix(auth/services/TokenService/validateMethod) is worse than fix(auth).

Breaking Changes

Breaking changes are indicated with an exclamation mark after the type/scope, or with a BREAKING CHANGE footer:

# Method 1: exclamation mark
feat(api)!: change authentication header format

# Method 2: footer
feat(api): change authentication header format

BREAKING CHANGE: Authorization header now uses Bearer prefix.
Previous format: Authorization: <token>
New format: Authorization: Bearer <token>

Tooling That Works With Conventional Commits

The real power of Conventional Commits comes from tooling built around the standard:

• commitlint — validates commit messages against the spec in CI
• semantic-release — automatically determines version bumps and generates changelogs
• standard-version — similar to semantic-release, simpler to configure
• release-please — Google's tool for automated GitHub releases from conventional commits
• CommitCraft AI — VS Code extension that generates conventional commits from your diff automatically

Automating Conventional Commits With CommitCraft AI

The main friction with Conventional Commits is remembering the format and choosing the right type. CommitCraft AI eliminates that friction by reading your actual code changes and determining the appropriate type, scope, and description automatically.

Common Questions

Should I use Conventional Commits for personal projects?

Yes, but the benefits are smaller. The main value is consistency across a team and automated tooling. For personal projects, the main benefit is that your git history will be readable when you come back to a project months later.

What if I commit the wrong type?

If you haven't pushed: git commit --amend. If you have pushed and no one has pulled: git push --force-with-lease. If it's already in main: don't amend, just write better commits going forward. Perfect adherence matters less than consistent improvement.