Conventional Commits Cheat Sheet 2025
Conventional Commits is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history, which makes it easier for automated tools to parse and for humans to understand (1).
Structure
A Conventional Commit message has a specific structure:
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
type: (Required)
This defines the kind of change. It is always in lowercase.
| Type | Description |
|---|---|
feat | A new feature or functionality |
fix | A bug fix |
docs | Documentation only changes |
style | Changes that do not affect the meaning of the code (e.g., formatting, semicolons, whitespace) |
refactor | A code change that neither fixes a bug nor adds a feature |
perf | A code change that improves performance |
test | Adding missing tests or correcting existing tests |
ci | Changes to our CI configuration files and scripts |
build | Changes that affect the build system or external dependencies |
chore | Other changes that don't modify src or test files |
scope: (Optional)
This provides additional contextual information about the change. It can be anything that identifies the part of the codebase where the change was made.
feat(api): add new user registration endpoint
fix(auth): correct password validation
description: (Required)
A short, concise summary of the change. It should be a single line and in the imperative mood ("add" not "added") (2).
fix(auth): correct password validation
body: (Optional)
A more detailed explanation of the commit. This is where you can provide more context, explain the motivation for the change, and describe the "before and after."
feat(api): add new user registration endpoint
The new endpoint /api/register allows users to create an account
with an email and password. It includes validation for both fields
and sends a confirmation email upon success.
footer(s): (Optional)
This section is for any closing information, most importantly for communicating breaking changes and referencing issues.
| Footer | Description |
|---|---|
BREAKING CHANGE: <description> | Marks a breaking change. This is critical for SemVer. This can also be a standalone footer. |
Closes #<issue-number> | References a GitHub or Jira issue that the commit resolves. |
Co-authored-by: <name> | To credit other contributors (3). |
Key Rules and Best Practices
-
Breaking Changes: Any commit that includes a
BREAKING CHANGEfooter, or atypefollowed by a!(e.g.,feat!:), indicates a breaking change and warrants a major version bump (SemVer).feat(api)!: remove old user endpoint
BREAKING CHANGE: The /api/user endpoint has been removed. Use /api/v2/users instead. -
Automated Tooling: Conventional Commits are designed to be parsed by tools. This enables automated version bumping, changelog generation, and more.
Example Commits
# New feature
feat: add dark mode to the user interface
# Bug fix with a body and issue reference
fix(auth): correct token refresh logic
This fix resolves an issue where the token refresh
failed on a bad request. It now correctly handles
the error response.
Closes #123
# Documentation change
docs: update API usage examples