Why structured commit messages matter
Well-structured commit messages improve collaboration, make code reviews easier, facilitate automated changelog generation, and help future developers (including yourself) understand why changes were made.
Conventional Commits Format
A specification for adding human and machine-readable meaning to commit messages
type(scope): subject
<blank line>
body
<blank line>
footer
Structure Breakdown:
- type: Indicates the kind of change (required)
- scope: Indicates the section of the codebase affected (optional)
- subject: A short, imperative description of the change (required)
- body: Detailed explanation of what and why (optional)
- footer: Information about breaking changes and issue references (optional)
Commit Types
Standardized prefixes to categorize your changes
| Type | Description |
|---|---|
| feat | A new feature |
| fix | A bug fix |
| docs | Documentation changes |
| style | Code style changes (formatting, missing semicolons, etc.) |
| refactor | Code changes that neither fix a bug nor add a feature |
| perf | Code changes that improve performance |
| test | Adding or correcting tests |
| build | Changes to build system or external dependencies |
| ci | Changes to CI configuration files and scripts |
| chore | Other changes that don't modify src or test files |
| revert | Reverts a previous commit |
Best Practices
Guidelines for writing effective commit messages
Subject Line
- Keep it under 50 characters
- Use imperative mood ("Add feature" not "Added feature")
- Don't end with a period
- Be specific and concise
Body
- Wrap at 72 characters
- Explain what and why, not how (code shows how)
- Use bullet points for multiple points (- or * followed by a space)
- Include context and background information
Footer
- Reference issues and pull requests: "Closes #123, #456"
- Note breaking changes: "BREAKING CHANGE: API now requires authentication"
- Mention co-authors if applicable: "Co-authored-by: Name <email>"
Implementation Strategy
How to adopt structured commit messages in your workflow
Team Adoption
- Document the commit message format in your project's README or CONTRIBUTING.md
- Use commit message templates to guide developers
- Consider using commit linting tools to enforce the format
- Start with a small team or project before rolling out widely
Useful Tools
- commitlint: Lints commit messages
- commitizen: Interactive commit message CLI
- husky: Git hooks to enforce commit message format
- standard-version: Automates versioning and CHANGELOG generation