git-commit-helper

Git Commit 助手

概述

遵循 Conventional Commits 规范，指导语义化版本决策、生成变更日志，并确保提交消息质量。本技能为版本控制沟通提供结构化方法，从而支持自动化工具并保持清晰的项目历史记录。

阶段 1：分析更改

分析暂存区中的差异，了解更改内容：

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

1. 确认受影响的文件和模块
2. 确定更改性质（新功能、错误修复、重构等）
3. 检查更改是否具有破坏性（API 更改、移除功能、更改契约）

停止 — 在了解更改的完整范围之前，不要编写提交消息。

阶段 2：分类并撰写

提交类型决策表

类型	使用场景	版本升级	示例
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 Commits 格式

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

[optional body]

[optional footer(s)]

作用域指南

作用域应标明受影响的代码库区域：

作用域策略	示例	使用场景
按模块	auth、billing、dashboard、api	按功能组织的代码库
按层	db、ui、middleware、config	按层组织的代码库
按包	@app/core、@app/shared	Monorepo
通用	deps、ci、lint、types	跨领域更改

规则：

• 使用小写字母和 kebab-case
• 在项目内保持一致
• 可选，但对于经常有 10 个以上文件更改的项目，建议使用
• 对于真正的跨领域更改，省略作用域

描述规则

• 使用祈使语气：“add”，而不是“added”或“adds”
• 首字母小写
• 末尾不加句号
• 最多 72 个字符（类型、作用域和描述合计）
• 描述更改了什么，而不是如何更改

阶段 3：编写提交消息

正文指南

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 个字符
• 解释更改原因（动机）
• 从较高层面说明更改内容
• 使用空行将正文与描述和页脚分隔开

破坏性更改

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()

有两种方式可以标记破坏性更改：

1. 在类型或作用域后添加 !：feat(api)!: description
2. 使用 BREAKING CHANGE: 页脚（可留出空间说明迁移细节）

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

停止 — 提交前先将提交消息交给用户审批。

阶段 4：评估版本影响

语义化版本（SemVer）：MAJOR.MINOR.PATCH

组成部分	递增时机	示例
MAJOR	破坏性更改（不兼容的 API 更改）	1.0.0 -> 2.0.0
MINOR	新功能（向后兼容）	1.0.0 -> 1.1.0
PATCH	错误修复（向后兼容）	1.0.0 -> 1.0.1

版本升级规则

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)

预发布版本

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

初始开发（0.x.y）

• 0.1.0：首个可用版本
• 0.x.y：API 尚不稳定；MINOR 版本可以包含破坏性更改
• 1.0.0：首个稳定版本；全面遵循 SemVer 规则

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

CHANGELOG.md 格式

# Changelog

## [1.2.0] - 2025-03-15

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

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

### Changed
- Update TypeScript to 5.4 (#240)

## [1.1.0] - 2025-02-28
...

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

提交类型	变更日志章节
feat	新增
fix	修复
perf	性能
refactor	变更
docs	文档
BREAKING CHANGE	重大变更（发布说明顶部）
chore、ci、build、style、test	通常不纳入

自动化工具

工具	用途
conventional-changelog	根据 git 历史生成变更日志
semantic-release	全自动版本管理和发布
changeset	用于 monorepo 的手动变更集文件
release-please	Google 的发布自动化工具

提交消息质量检查清单

必须通过

• 使用约定式提交格式（type(scope): description）
• 类型来自允许的列表
• 描述使用祈使语气
• 描述总长度少于 72 个字符
• 描述末尾没有句号
• 明确标记重大变更

应尽量通过

• 范围准确标识受影响的部分
• 对于非简单变更，正文解释原因（WHY），而不只是内容（WHAT）
• 引用问题 / 工单编号（Closes #123、Refs #456）
• 每个提交只包含一个逻辑变更（原子提交）
• 主分支历史中没有“WIP”或“temp”提交

拆分提交指南

何时拆分决策表

条件	操作
变更涉及不同模块 / 功能	拆分为多个独立提交
重构与新增功能合并在一起	拆分：先重构，再实现功能
为现有代码新增测试，并新增功能	拆分：先添加测试，再实现功能
配置变更与代码变更	拆分为多个独立提交
跨多个文件的单一逻辑变更	保持为一个提交

如何拆分

# Interactive staging for partial commits
git add -p                    # Stage hunks interactively
git add path/to/specific/file # Stage specific files

# 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"

反模式 / 常见错误

反模式	错误原因	建议做法
为新功能使用 fix 类型	会误导版本升级自动化流程	为新功能使用 feat
压缩有意义的历史记录	丢失开发过程的上下文	保留原子提交，仅压缩 WIP 提交
使用 --no-verify 跳过钩子	绕过质量门禁	修复钩子执行失败的问题
修改已发布 / 已推送的提交	破坏其他开发者的历史记录	创建新提交
提交消息为空或只有“.”	无法为未来的读者提供任何信息	编写描述性消息
将格式调整与逻辑变更混在一起	无法单独撤销其中一项	拆分为不同提交
使用“将 X 改为 Y”重复描述差异	没有提供差异之外的信息	描述变更的原因
修改 20 个以上文件的超大提交	无法审查或二分定位	拆分为逻辑清晰的原子提交

集成点

技能	集成方式
finishing-a-development-branch	压缩后的提交消息遵循约定格式
code-review	提交质量属于审查清单的一部分
deployment	版本升级会触发发布流水线
planning	提交范围与计划任务的粒度一致
verification-before-completion	提交前验证测试通过

技能类型

灵活 — 强烈建议使用约定式提交格式，但也可以根据项目现有约定进行调整。使用约定式提交时，版本升级规则是确定的。变更日志章节会直接根据提交类型映射。