Following a consistent and clear standard for Git commit messages is crucial for team collaboration, automated versioning, and maintaining a readable project history. The most widely adopted standard is Conventional Commits.
The Conventional Commits Format
A commit message is structured as follows:
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
1. The Commit Header (Required)
The header is the most important part and must be a single line: <type>(<scope>): <description>
<type>: Defines the category of the change.
| Type | Description |
|---|---|
| feat | A new feature for the user. |
| fix | A bug fix for the user. |
| docs | Changes to documentation only. |
| style | Formatting changes that don't affect code logic (whitespace, etc.). |
| refactor | A code change that neither fixes a bug nor adds a feature. |
| test | Adding missing tests or correcting existing ones. |
| chore | Changes to the build process or auxiliary tools (e.g., updating deps). |
| perf | A code change that improves performance. |
| ci | Changes to Continuous Integration configuration files and scripts. |
| build | Changes that affect the build system or external dependencies. |
[optional scope]: A noun in parentheses describing the section of the codebase affected (e.g., (api), (auth), (ui)).
<description>: A short, imperative-mood summary of the change.
- Do:
feat(auth): add Google OAuth login - Don't:
feat(auth): added Google OAuth login(past tense) - Don't:
feat(auth): I added Google OAuth login(using "I")
Breaking Change Indicator: To indicate a change that breaks backward compatibility, add a ! after the type/scope. This requires a BREAKING CHANGE: section in the footer.
refactor(auth)!: rename User model to AppUser
2. The Body (Optional)
- Use the body to explain the "why" and "how" of the change, not the "what." The code itself shows what changed.
- Provide context: What was the problem? How does this solution address it?
- Separate the header from the body with a single blank line.
- It's good practice to wrap body lines at 72 characters for readability in various Git tools.
3. The Footer (Optional)
Issue Tracking: Reference issue tracker IDs. Keywords like
Fixes #123orCloses #45will automatically close the referenced issue on platforms like GitHub.Breaking Changes: If you used
!in the header, you MUST include aBREAKING CHANGE:section in the footer explaining what broke and what the migration path is for consumers of your code.BREAKING CHANGE: The `User` model has been renamed to `AppUser`. All downstream services must update their data models to use `AppUser`.
Examples
Simple Fix
fix(api): correct user lookup logic for deactivated accounts
New Feature with a Body
feat(ui): add dark mode toggle to user settings
Provides users with the ability to switch between light and dark
themes. The selected theme is persisted in localStorage to ensure
the user's choice is remembered across sessions.
Refactor with a Breaking Change
refactor(auth)!: replace JWT with session-based authentication
BREAKING CHANGE: The authentication mechanism has been changed from
stateless JWTs to stateful sessions. The `/api/login` endpoint
no longer returns a JWT. Clients must now handle cookies to
maintain session state.