Complete Git Commit Message Guide

Writing good commit messages is an essential skill for any developer. This comprehensive guide will teach you everything you need to know about crafting professional, standardized commit messages following the Conventional Commits specification.

Commit Types

Commit Message Structure

Basic Format

Components Explained

1. Type (Required)

• Choose from the types listed above
• Always lowercase
• Example: feat, fix, docs

2. Scope (Optional)

• Specifies the part of codebase affected
• Use parentheses
• Examples: (auth), (api), (ui), (parser)

3. Subject (Required)

• Brief summary of the change
• Use imperative mood ("add" not "added" or "adds")
• Don't capitalize first letter
• No period at the end
• Maximum 50-72 characters

4. Body (Optional)

• Detailed explanation of the change
• Use imperative mood
• Explain what and why, not how
• Wrap at 72 characters
• Separate from subject with blank line

5. Footer (Optional)

• Breaking changes: BREAKING CHANGE: <description>
• Issue references: Closes #123, Fixes #456, Relates to #789
• Co-authors: Co-authored-by: Name <email>

Writing Rules

✅ DO:

• Use imperative mood: "add feature" not "added feature"
• Keep subject line under 50 characters (hard limit 72)
• Start subject with lowercase
• Separate subject from body with blank line
• Wrap body at 72 characters
• Use body to explain what and why vs. how
• Reference issues and pull requests in footer
• Use present tense

❌ DON'T:

• Don't end subject line with period
• Don't use past tense
• Don't include unnecessary details
• Don't be vague ("fixed stuff", "updated code")
• Don't combine multiple unrelated changes

Examples

Simple Commit

Commit with Body

Breaking Change

Multiple Issues

With Scope Examples

Best Practices

1. Atomic Commits: Each commit should represent one logical change
2. Commit Often: Small, frequent commits are better than large ones
3. Review Before Committing: Use git diff to review changes
4. Meaningful Messages: Future you (and your team) will thank you
5. Consistency: Follow your team's conventions
6. Test First: Ensure code works before committing

Conventional Commits Specification

This guide follows the Conventional Commits specification, which:

• Provides a standardized format for commit messages
• Enables automatic changelog generation
• Simplifies semantic versioning
• Makes it easier to understand project history

Quick Reference

Good Examples

Bad Examples

Tools & Automation

• commitlint: Lint commit messages
• husky: Git hooks for commit message validation
• commitizen: Interactive commit message builder
• standard-version: Automated versioning and changelog

Common Scenarios

Feature Development

Bug Fixes

Documentation Updates

Dependency Management

Configuration Changes

Multi-Line Commit Messages

For complex changes, use the full commit message format:

Team Conventions

When working in a team, establish conventions for:

1. Scope naming: Agree on component/module names
2. Issue references: How to link commits to tickets
3. Breaking changes: How to communicate API changes
4. Review process: When to amend vs. create new commits

Advanced Patterns

Monorepo Commits

Multiple Co-authors

Reverting Commits

Troubleshooting Common Mistakes

Mistake 1: Vague Messages

❌ Bad: fix: bug fix ✅ Good: fix(auth): resolve token expiration issue

Mistake 2: Multiple Changes

❌ Bad: feat: add login, fix header, update docs ✅ Good: Create separate commits for each change

Mistake 3: Missing Context

❌ Bad: refactor: change code ✅ Good: refactor(utils): extract date formatting to utility function

Mistake 4: Wrong Tense

❌ Bad: feat: added new feature ✅ Good: feat: add new feature

Integrating with Your Workflow

Pre-commit Hooks

Commitlint Configuration

Commitizen Setup

Changelog Generation

Well-formatted commits enable automated changelog generation:

This creates a CHANGELOG.md with all your changes organized by type!

Conclusion

Good commit messages are a love letter to your future self and your team. They:

• Make code review easier
• Enable automated tooling
• Improve project documentation
• Facilitate debugging and maintenance
• Support better collaboration

By following this guide and the Conventional Commits specification, you'll write commit messages that are clear, consistent, and valuable for the entire development lifecycle.

---

References:

• Conventional Commits Specification
• Semantic Versioning
• Git Best Practices

Tools:

• commitlint
• husky
• commitizen
• standard-version

Remember: Consistency is key. Choose a convention and stick to it!