git-commit-guide

Git Commit Convention Skill Pack

Follow the Conventional Commits specification to improve team collaboration quality and code maintainability.

Commit Message Format

<type>(<scope>): <subject>

<body>

<footer>

Basic Format

<类型>[可选作用域]: <描述>

Example：

feat(api): 添加用户认证接口
fix(database): 修复连接池泄漏问题
docs(readme): 更新安装说明

Commit Type (Type)

Type	Description	Example
feat	New feature	`feat(user): 添加用户注册功能`
fix	Bug fix	`fix(login): 修复密码验证错误`
docs	Documentation changes	`docs(api): 更新 API 文档`
style	Code formatting (does not affect logic)	`style: 统一代码缩进`
refactor	Refactoring (neither a new feature nor a fix)	`refactor(auth): 优化认证逻辑`
perf	Performance optimization	`perf(query): 优化数据库查询`
test	Test-related	`test(user): 添加用户模块单元测试`
build	Build system or external dependencies	`build: 升级 Spring Boot 到 3.0`
ci	CI configuration files and scripts	`ci: 添加 GitHub Actions 配置`
chore	Other changes that do not modify source code	`chore: 更新 .gitignore`
revert	Revert a previous commit	`revert: 回滚 feat(api): xxx`

Scope

The scope indicates the affected module or component; it is optional but recommended.

Common Scope Examples：

user - User module
auth - Authentication module
api - API interface
database - Database
config - Configuration
ui - User interface

Subject

Use the imperative mood, present tense
Start with a lowercase letter
Do not end with a period
Be concise and clear, keep it within 50 characters

✅ Good description：

feat(api): 添加用户注册接口
fix(login): 修复密码加密错误

❌ Bad description：

feat(api): 添加了用户注册接口。
fix: 修复bug

Body

Explain in detail the motivation for the change and how it compares with previous behavior.

Format Requirements：

Use the imperative mood, present tense
Should explain "why" rather than "what"
Each line should not exceed 72 characters

Example：

fix(auth): 修复 JWT Token 验证失败问题

之前使用的签名算法与解析算法不一致，导致 Token 验证总是失败。
现在统一使用 HS256 算法，并添加了算法一致性检查。

Footer

Used to record breaking changes and closed issues.

Breaking Changes

BREAKING CHANGE: 删除了 v1 版本的 API

请迁移到 v2 版本，详见迁移指南。

Close Issue

Closes #123
Closes #456, #789

Complete Example

Example 1: New feature

feat(user): 添加用户头像上传功能

支持上传 JPG、PNG 格式的图片，最大 5MB。
自动生成缩略图并存储到 OSS。

Closes #234

Example 2: Bug fix

fix(order): 修复订单金额计算错误

在计算优惠券折扣时未考虑最小金额限制，
导致部分订单金额为负数。现已添加金额验证。

Closes #567

Example 3: Breaking change

feat(api): 重构用户认证 API

BREAKING CHANGE: 移除了 /api/v1/auth 端点

请使用新的 /api/v2/auth 端点，返回格式已变更。
详见 API 文档：https://example.com/api-docs

Closes #890

Git Hooks Configuration

Commit Message Validation

Create .git/hooks/commit-msg：

#!/bin/bash
commit_msg_file=$1
commit_msg=$(cat "$commit_msg_file")

# 验证格式
if ! echo "$commit_msg" | grep -qE "^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?: .+"; then
    echo "错误：提交信息不符合规范"
    echo "格式：<type>(<scope>): <subject>"
    echo "示例：feat(api): 添加用户注册接口"
    exit 1
fi

Using Commitizen

# 安装
npm install -g commitizen cz-conventional-changelog

# 配置
echo '{ "path": "cz-conventional-changelog" }' > ~/.czrc

# 使用
git cz

Best Practices

Do only one thing per commit: A commit should address only one problem or add only one feature
Commits should be complete: Ensure the code after the commit can run normally
Commit frequently: Take small, quick steps; do not accumulate too many changes
Pull before pushing: Before committing, first git pull --rebase
Avoid mixed changes: Do not mix multiple types of changes in the same commit

Frequently Asked Questions

Q: When should I use chore instead of feat?

A: If the change does not affect users or functionality (such as updating dependencies or modifying configuration), use chore。

Q: How do I distinguish refactoring from performance optimization?

A: If the main purpose is to improve performance, use perf; if it is to improve code structure, use refactor。

Q: What if one commit fixes multiple Bugs?

A: It is recommended to split it into multiple commits, with each commit fixing only one Bug.

Recommended Tools

Commitizen: Interactive commit message generation
commitlint: Commit message format validation
husky: Git Hooks management
standard-version: Automatically generate CHANGELOG

About this skill