git-commit-helper

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Git Commit Helper

Git 提交助手

Overview

概述

Enforce conventional commit standards, guide semantic versioning decisions, generate changelogs, and ensure commit message quality. This skill provides a structured approach to version control communication that enables automated tooling and clear project history.

强制遵循conventional commit规范，指导semantic versioning决策，生成变更日志，确保提交信息质量。该技能为版本控制的提交信息提供了结构化方案，可支持自动化工具链运行，同时保持清晰的项目历史。

Phase 1: Analyze Changes

阶段1：分析更改

Analyze the staged diff to understand what was changed:

bash

git diff --cached --stat
git diff --cached

Identify the files and modules affected
Determine the nature of the change (new feature, bug fix, refactoring, etc.)
Check if the change is breaking (API changes, removed features, changed contracts)

STOP — Do NOT write a commit message until you understand the full scope of changes.

分析暂存区的diff以了解更改内容：

bash

git diff --cached --stat
git diff --cached

识别受影响的文件和模块
确定更改的性质（新增功能、漏洞修复、重构等）
检查更改是否具有破坏性（API变更、功能移除、契约修改等）

停止 — 在完全理解更改范围前，请勿编写提交信息。

Phase 2: Classify and Compose

阶段2：分类与编写

Commit Type Decision Table

提交类型决策表

Type	When to Use	Version Bump	Example
`feat`	New feature for the user	MINOR	`feat(auth): add OAuth2 login flow`
`fix`	Bug fix for the user	PATCH	`fix(api): handle null response in user endpoint`
`docs`	Documentation only changes	None	`docs(readme): update installation steps`
`style`	Formatting, missing semicolons, etc.	None	`style(lint): fix trailing whitespace`
`refactor`	Code change with no behavior change	None	`refactor(utils): extract date formatting helpers`
`perf`	Performance improvement	PATCH	`perf(query): add index for user lookup`
`test`	Adding or correcting tests	None	`test(auth): add login failure scenarios`
`chore`	Maintenance, deps, tooling	None	`chore(deps): update typescript to 5.4`
`ci`	CI/CD configuration changes	None	`ci(github): add Node 20 to test matrix`
`build`	Build system or external dependencies	None	`build(webpack): optimize chunk splitting`

类型	使用场景	版本号升级	示例
`feat`	面向用户的新增功能	MINOR	`feat(auth): add OAuth2 login flow`
`fix`	面向用户的漏洞修复	PATCH	`fix(api): handle null response in user endpoint`
`docs`	仅文档相关更改	无	`docs(readme): update installation steps`
`style`	格式调整、缺少分号等	无	`style(lint): fix trailing whitespace`
`refactor`	不改变行为的代码变更	无	`refactor(utils): extract date formatting helpers`
`perf`	性能优化	PATCH	`perf(query): add index for user lookup`
`test`	新增或修正测试	无	`test(auth): add login failure scenarios`
`chore`	维护、依赖更新、工具调整	无	`chore(deps): update typescript to 5.4`
`ci`	CI/CD配置变更	无	`ci(github): add Node 20 to test matrix`
`build`	构建系统或外部依赖变更	无	`build(webpack): optimize chunk splitting`

Conventional Commit Format

Conventional Commit 格式

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

<type>(<scope>): <description>

[可选正文]

[可选脚注]

Scope Guidelines

范围(Scope)指南

Scope should identify the area of the codebase affected:

Scope Strategy	Examples	When to Use
By module	`auth` , `billing` , `dashboard` , `api`	Feature-organized codebases
By layer	`db` , `ui` , `middleware` , `config`	Layer-organized codebases
By package	`@app/core` , `@app/shared`	Monorepos
General	`deps` , `ci` , `lint` , `types`	Cross-cutting changes

Rules:

Lowercase, kebab-case
Keep consistent within a project
Optional but recommended for projects with 10+ files changed regularly
Omit scope for truly cross-cutting changes

范围应当标识代码库受影响的区域：

范围策略	示例	适用场景
按模块划分	`auth` , `billing` , `dashboard` , `api`	按功能组织的代码库
按层级划分	`db` , `ui` , `middleware` , `config`	按层级组织的代码库
按包划分	`@app/core` , `@app/shared`	Monorepo场景
通用分类	`deps` , `ci` , `lint` , `types`	跨模块更改

规则：

小写，使用短横线命名法(kebab-case)
项目内保持一致
对于常规更改文件数超过10个的项目为可选但推荐使用
完全跨模块的更改可以省略范围

Description Rules

描述规则

Use imperative mood: "add" not "added" or "adds"
No capital first letter
No period at the end
Maximum 72 characters (type + scope + description combined)
Describe WHAT changed, not HOW

使用祈使语气：用「add」而非「added」或「adds」
首字母不要大写
末尾不要加句号
总长度（类型+范围+描述合计）不超过72字符
描述更改的内容，而非实现方式

Phase 3: Write the Commit Message

阶段3：编写提交信息

Body Guidelines

正文指南

feat(cart): add quantity update functionality

Users can now change item quantities directly in the cart
without removing and re-adding items. The quantity selector
supports values from 1 to 99 with real-time price updates.

Closes #234

Wrap at 72 characters
Explain WHY the change was made (motivation)
Explain WHAT changed at a high level
Use blank line to separate from description and footer

feat(cart): add quantity update functionality

Users can now change item quantities directly in the cart
without removing and re-adding items. The quantity selector
supports values from 1 to 99 with real-time price updates.

Closes #234

每行长度不超过72字符
解释更改的原因（动机）
从高维度说明更改的内容
使用空行分隔描述、正文和脚注

Breaking Changes

破坏性更改

feat(api)!: change user endpoint response format

BREAKING CHANGE: The /api/users endpoint now returns a paginated
response object instead of a plain array. Clients must update
to read from the `data` field.

Migration guide:
- Before: const users = await fetch('/api/users').json()
- After:  const { data: users } = await fetch('/api/users').json()

Two ways to indicate breaking changes:

```
!
```
after type/scope:
```
feat(api)!: description
```
```
BREAKING CHANGE:
```
footer (provides space for migration details)

Both trigger a MAJOR version bump.

STOP — Present the commit message to the user for approval before committing.

feat(api)!: change user endpoint response format

BREAKING CHANGE: The /api/users endpoint now returns a paginated
response object instead of a plain array. Clients must update
to read from the `data` field.

Migration guide:
- Before: const users = await fetch('/api/users').json()
- After:  const { data: users } = await fetch('/api/users').json()

两种标识破坏性更改的方式：

在类型/范围后添加
```
!
```
：
```
feat(api)!: description
```
添加
```
BREAKING CHANGE:
```
脚注（可提供迁移说明的空间）

两种方式都会触发MAJOR版本号升级。

停止 — 提交前请先将提交信息提交给用户确认。

Phase 4: Assess Version Impact

阶段4：评估版本影响

Semantic Versioning (SemVer): MAJOR.MINOR.PATCH

语义化版本(SemVer)：MAJOR.MINOR.PATCH

Component	Increment When	Example
MAJOR	Breaking changes (incompatible API changes)	1.0.0 -> 2.0.0
MINOR	New features (backward compatible)	1.0.0 -> 1.1.0
PATCH	Bug fixes (backward compatible)	1.0.0 -> 1.0.1

组成部分	升级触发条件	示例
MAJOR	破坏性更改（不兼容的API变更）	1.0.0 -> 2.0.0
MINOR	新增功能（向后兼容）	1.0.0 -> 1.1.0
PATCH	漏洞修复（向后兼容）	1.0.0 -> 1.0.1

Version Bumping Rules

版本号升级规则

Commits since last release:
  fix(auth): handle expired tokens       -> PATCH
  feat(search): add fuzzy matching       -> MINOR (overrides PATCH)
  fix(ui): correct button alignment      -> already MINOR
  feat(api)!: change response format     -> MAJOR (overrides MINOR)

Result: MAJOR bump (highest wins)

Commits since last release:
  fix(auth): handle expired tokens       -> PATCH
  feat(search): add fuzzy matching       -> MINOR (覆盖PATCH升级)
  fix(ui): correct button alignment      -> 已为MINOR升级
  feat(api)!: change response format     -> MAJOR (覆盖MINOR升级)

Result: MAJOR bump (最高优先级生效)

Pre-Release Versions

预发布版本

1.0.0-alpha.1    -> Early testing
1.0.0-beta.1     -> Feature complete, testing
1.0.0-rc.1       -> Release candidate
1.0.0            -> Stable release

1.0.0-alpha.1    -> 早期测试版本
1.0.0-beta.1     -> 功能完备，测试阶段
1.0.0-rc.1       -> 发布候选版本
1.0.0            -> 稳定版本

Initial Development (0.x.y)

初始开发阶段(0.x.y)

0.1.0: First usable version
0.x.y: API is not stable; MINOR can include breaking changes
1.0.0: First stable release; SemVer rules fully apply

0.1.0: 首个可用版本
0.x.y: API不稳定，MINOR升级可包含破坏性更改
1.0.0: 首个稳定版本，完全适用SemVer规则

Phase 5: Generate Changelog (if applicable)

阶段5：生成变更日志（如适用）

CHANGELOG.md Format

CHANGELOG.md 格式

markdown

undefined

markdown

undefined

Changelog

[1.2.0] - 2025-03-15

Added

新增

Fuzzy search matching for product catalog (#234)
Bulk export functionality for reports (#245)

商品目录模糊搜索功能 (#234)
报表批量导出功能 (#245)

Fixed

修复

Handle expired authentication tokens gracefully (#230)
Correct button alignment on mobile viewports (#232)

优雅处理过期的认证令牌 (#230)
修正移动端视口下的按钮对齐问题 (#232)

Changed

变更

Update TypeScript to 5.4 (#240)

升级TypeScript到5.4版本 (#240)

[1.1.0] - 2025-02-28

...

undefined

...

undefined

Commit Type to Changelog Section Mapping

提交类型到变更日志章节映射

Commit Type	Changelog Section
`feat`	Added
`fix`	Fixed
`perf`	Performance
`refactor`	Changed
`docs`	Documentation
`BREAKING CHANGE`	Breaking Changes (top of release)
`chore` , `ci` , `build` , `style` , `test`	Typically excluded

提交类型	变更日志章节
`feat`	新增
`fix`	修复
`perf`	性能优化
`refactor`	变更
`docs`	文档
`BREAKING CHANGE`	破坏性更改（版本章节顶部）
`chore` , `ci` , `build` , `style` , `test`	通常不纳入

Automation Tools

自动化工具

Tool	Use Case
`conventional-changelog`	Generate changelog from git history
`semantic-release`	Fully automated versioning + publishing
`changeset`	Manual changeset files for monorepos
`release-please`	Google's release automation

工具	使用场景
`conventional-changelog`	从Git历史生成变更日志
`semantic-release`	全自动化版本管理+发布
`changeset`	Monorepo场景的手动变更记录文件管理
`release-please`	Google出品的发布自动化工具

Commit Message Quality Checklist

提交信息质量检查清单

Must Pass

必须满足

Uses conventional commit format (
```
type(scope): description
```
)
Type is from the allowed list
Description uses imperative mood
Description is under 72 characters total
No period at end of description
Breaking changes are clearly marked

遵循conventional commit格式 (
```
type(scope): description
```
)
类型属于允许的列表范围
描述使用祈使语气
描述总长度不超过72字符
描述末尾没有句号
破坏性更改已明确标识

Should Pass

建议满足

Scope accurately identifies the affected area
Body explains WHY, not just WHAT (for non-trivial changes)
References issue/ticket number (
```
Closes #123
```
,
```
Refs #456
```
)
Single logical change per commit (atomic commits)
No "WIP" or "temp" commits in main branch history

范围准确标识了受影响的区域
正文解释了更改的原因，而非仅说明内容（针对非 trivial 更改）
关联了issue/工单编号 (
```
Closes #123
```
,
```
Refs #456
```
)
每个提交仅包含单逻辑更改（原子提交）
主分支历史中不存在「WIP」或「临时」提交

Commit Splitting Guide

提交拆分指南

When to Split Decision Table

拆分决策表

Condition	Action
Changes to different modules/features	Split into separate commits
Refactor combined with feature addition	Split: refactor first, then feature
Test additions for existing code + new feature	Split: tests first, then feature
Config changes + code changes	Split into separate commits
Single logical change across multiple files	Keep as one commit

条件	操作
更改涉及不同模块/功能	拆分为独立提交
重构与功能新增混合	拆分：先提交重构，再提交功能
为现有代码新增测试 + 新增功能	拆分：先提交测试，再提交功能
配置更改 + 代码更改	拆分为独立提交
跨多个文件的单逻辑更改	保留为单个提交

How to Split

拆分方法

bash

undefined

bash

undefined

Interactive staging for partial commits

交互式暂存实现部分提交

git add -p # Stage hunks interactively git add path/to/specific/file # Stage specific files

git add -p # 交互式暂存代码块 git add path/to/specific/file # 暂存指定文件

Example: split refactor + feature

示例：拆分重构+功能提交

git add src/utils/date.ts git commit -m "refactor(utils): extract date formatting helpers"

git add src/components/DatePicker.tsx src/components/DatePicker.test.tsx git commit -m "feat(ui): add date range picker component"

undefined

git add src/utils/date.ts git commit -m "refactor(utils): extract date formatting helpers"

git add src/components/DatePicker.tsx src/components/DatePicker.test.tsx git commit -m "feat(ui): add date range picker component"

undefined

Anti-Patterns / Common Mistakes

反模式/常见错误

Anti-Pattern	Why It Is Wrong	What to Do Instead
`fix` type for a new feature	Misleads version bump automation	Use `feat` for new functionality
Squashing meaningful history	Loses context of development process	Keep atomic commits, squash only WIP
Using `--no-verify` to skip hooks	Bypasses quality gates	Fix the hook failure instead
Amending published/pushed commits	Breaks other developers' history	Create new commit instead
Empty or "." commit messages	Zero information for future readers	Write a descriptive message
Mixing formatting with logic changes	Cannot revert one without the other	Separate into distinct commits
"change X to Y" duplicating the diff	Adds no information beyond the diff	Describe WHY the change was made
Huge commits touching 20+ files	Impossible to review or bisect	Split into logical atomic commits

反模式	错误原因	正确做法
新功能使用 `fix` 类型	误导版本号自动化升级	新功能使用 `feat` 类型
压缩有意义的提交历史	丢失开发过程上下文	保留原子提交，仅压缩WIP提交
使用 `--no-verify` 跳过钩子	绕过质量门禁	修复钩子触发的错误
amend已发布/推送的提交	破坏其他开发者的本地历史	新建提交替代
空提交信息或仅用「.」作为提交信息	对后续查看者没有任何信息价值	编写有描述性的提交信息
格式调整与逻辑更改混合提交	无法单独回滚其中一类更改	拆分为独立提交
「将X改为Y」这类重复diff内容的描述	没有提供diff之外的额外信息	描述更改的原因
涉及20+文件的巨型提交	无法评审或二分定位问题	拆分为逻辑独立的原子提交

Integration Points

集成点

Skill	Integration
`finishing-a-development-branch`	Squash commit message follows conventional format
`code-review`	Commit quality is part of review checklist
`deployment`	Version bumps trigger release pipelines
`planning`	Commit scoping aligns with plan task granularity
`verification-before-completion`	Verify tests pass before committing

技能	集成方式
`finishing-a-development-branch`	压缩合并的提交信息遵循conventional格式
`code-review`	提交质量是评审检查项的一部分
`deployment`	版本号升级触发发布流水线
`planning`	提交范围与规划任务粒度对齐
`verification-before-completion`	提交前验证测试通过

Skill Type

技能类型

FLEXIBLE — Conventional commit format is strongly recommended but can be adapted to existing project conventions. Version bumping rules are deterministic when conventional commits are used. Changelog sections map directly from commit types.

灵活适配 — Conventional commit格式为强推荐规范，但可适配现有项目约定。使用conventional commit时版本号升级规则是确定的，变更日志章节可直接与提交类型映射。