Why a Unified Commit Specification is Needed?¶

In team collaboration, writing Git commit messages is essential after every code change. If commit messages are messy (e.g., “Fixed something” or “Modified a bug”), it causes several issues:

• Difficult Code Review: Others must spend time analyzing the code to understand changes
• Chaotic Version Iteration: Version history becomes hard to interpret, making it unclear if a commit added features or fixed bugs
• Broken Automation: Tools for generating release logs or linking to issues may fail

A unified commit specification acts like a “label” for each change, allowing everyone to quickly understand the purpose and content of the modification.

Step 1: Understanding the Commit Message Format¶

The most popular specification is Conventional Commits, which structures commit messages into clear sections:

<type>[optional scope]: <description>

[optional body]

[optional footer]

1. Type: Indicates the “nature” of the commit¶

Must be one of these types (选错会误导版本迭代):
- feat: New feature (e.g., “Add user login button”)
- fix: Bug fix (e.g., “Fix shopping cart calculation error”)
- docs: Documentation updates (e.g., “Update API documentation”)
- style: Formatting changes (no logic impact, e.g., indentation)
- refactor: Code refactoring (neither new nor fixing, e.g., optimize algorithm)
- test: Add/modify tests
- chore: Miscellaneous (e.g., config changes, dependency updates)

Example: feat: Add user registration page

2. Description: Concisely explains the change¶

• Keep it short (≤50 characters) but clear
• Start with a verb (e.g., “Add”, “Fix”, “Optimize”)
• No questions/exclamations—state facts directly

Incorrect: Modified page layout (too vague)
Correct: Optimize homepage navigation layout (clearly specifies what was changed)

3. Body (optional): Detailed explanation of changes¶

Use a blank line to separate from description for more details:
- Why the change was made
- Specific features implemented
- Problems solved

Example:

fix: Fix mobile menu click not working

- Mobile menu button click event wasn't triggered
- Found incorrect event delegation selector
- Fixed to use correct child element selector

4. Footer (optional): Relate to issues or note impact¶

• Link to issues (e.g., Closes #123 for fixing issue #123)
• Use BREAKING CHANGE: for API-breaking changes

Example:

feat: Add user permission management

- Support admin/regular user role distinction
- Add permission middleware

Closes #456  // Links to task #456

Step 2: Create a Team Commit Template¶

Method 1: Global Configuration (For All Projects)¶

1. Create template file: Create a text file (e.g., .gitmessage) in your home directory (Windows: C:\Users\Username, Mac/Linux: ~):

# Commit Message Template

## Type (Required):
- feat: New Feature
- fix: Bug Fix
- docs: Documentation
- style: Formatting
- refactor: Code Refactoring
- test: Testing
- chore: Miscellaneous

## Description (Required, ≤50 chars):
[Start with a verb to describe the change, e.g., "Add user registration"]

## Body (Optional, multi-line):
[Explain the reason, implementation details, or testing]

## Footer (Optional):
- Related Issue: Closes #Number
- Breaking Change: BREAKING CHANGE: [Description]

2. Configure Git to use the template:

git config --global commit.template ~/.gitmessage

Subsequent git commit commands will automatically open this template.

Method 2: Project-Level Template (For Current Project Only)¶

1. Create .gitmessage in your project root with the same content above.
2. Configure the project-specific template:

git config commit.template .gitmessage

Step 3: Using the Template to Commit Code¶

Quick Commit (Single-Line Message)¶

For simple changes:

git commit -m "feat: Fix login button styling"

Detailed Commit (Using the Template)¶

For complex changes:

git commit

This opens the editor with the template. After filling, save and exit (in Vim: ESC → :wq).

Tool Assisted: Enforce Commit规范¶

To ensure strict adherence, use tools for automated checks:

1. Commitlint: Validate commit message format¶

• Install: npm install --save-dev @commitlint/cli @commitlint/config-conventional
• Create commitlint.config.js:

  module.exports = {extends: ['@commitlint/config-conventional']}

• Commitlint will reject invalid messages before commit.

2. Husky: Run checks before commit¶

Husky manages Git hooks to enforce rules before commits/pushes:

• Install: npm install husky --save-dev
• Initialize: npx husky install
• Add commit-msg hook:

  npx husky add .husky/commit-msg 'npx --no -- commitlint --edit $1'

Invalid commits will now be blocked by the hooks.

Common Errors & Best Practices¶

1. Incorrect Type: Using chore instead of fix for bugs
2. Vague Description: “Fixed a bug” instead of specific details
3. Redundant Body: Repeating code details already visible in diffs
4. Incomplete Issue Link: Using #123 instead of Closes #123

Correct Example:

fix: Fix shopping cart quantity calculation

- Cart total not hiding when quantity is 0
- Found logical error in conditional check
- Fixed to use >0 instead of ≥0

Closes #789  // Links to specific issue

Conclusion¶

A规范 commit message is like a “user manual” for code changes, enabling smoother team collaboration. Remember: clear type, concise description, detailed body, and linked footnotes are key. Even for personal projects, this habit simplifies future code maintenance.

Share the .gitmessage file and tool configurations (Commitlint/Husky) with the team to build consistent development practices!