git-commit

Conventional Commits

默认提交格式：Conventional Commits。 除非项目在其他位置定义了自己的提交约定（例如 CLAUDE.md、AGENTS.md、贡献指南等），否则所有提交和 PR/MR 标题都使用此格式。项目特定规则始终优先。

适用场景

• 进行任何 Git 提交——此规范定义了必需的格式
• 创建 PR/MR 标题——压缩合并会将标题用作提交消息
• 撰写压缩合并消息——必须遵循相同格式
• 检查提交消息格式——根据这些规则进行验证

关键规则

1. 项目规则优先于此规范——如果项目定义了提交消息约定（例如问题编号前缀、自定义格式等），请遵循项目规则。没有项目特定规则时，此规范为默认格式。
2. 类型为必填项——提交时必须带类型前缀
3. 描述使用小写字母，采用祈使语气，不加句号：fix: handle null response，而不是 Fix: Handled null response.
4. 不添加 Co-Authored-By 署名——绝不在提交消息中添加
5. 描述变更，而非过程——绝不要将审查来源写入消息（例如 fix: coderabbit round 2 fixes、fix: address review feedback）；应说明提交实际变更了什么。变更的起因已记录在 PR 及其讨论串中。
6. 不写填充内容——通常只需描述即可；仅当描述和差异无法传达某些信息时，才添加正文（例如不兼容变更的详细信息、迁移步骤、不明显的限制条件）。绝不复述差异内容。

---

提供商检测

检测 Git 提供商，以使用正确的 CLI：

git remote get-url origin

远程 URL 包含	提供商	CLI	PR 术语
github.com	GitHub	gh	PR
gitlab.com 或自托管 GitLab	GitLab	glab	MR

如果无法确定，或两种情况同时存在，请询问用户。

---

格式

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

[optional body]

[optional footer(s)]

类型

类型	适用场景
feat	新功能或新能力
fix	修复 Bug
docs	仅修改文档
style	格式、空白字符、分号（不改变逻辑）
refactor	既不修复 Bug 也不添加功能的代码变更
perf	性能改进
test	添加或更新测试
build	构建系统或外部依赖
ci	CI/CD 配置
chore	维护任务、工具、配置

规则

1. 类型为必填项——提交时必须带类型前缀
2. 范围可选，但对于多模块仓库，建议填写：feat(auth): add OAuth2 flow
3. 描述使用小写字母，采用祈使语气，不加句号：fix: handle null response，而不是 Fix: Handled null response.
4. 不兼容变更在类型或范围后使用 !：feat(api)!: remove v1 endpoints
5. PR/MR 标题遵循相同格式——压缩合并会将 PR/MR 标题用作提交消息
6. 不添加 Co-Authored-By 署名——绝不在提交消息中添加
7. 描述变更，而非过程——说明变更了什么，绝不要说明审查者为何要求修改（参见下文“审查修复提交”）
8. 正文可选且很少使用——仅在描述和差异无法传达信息时添加；绝不复述差异内容或用叙述填充正文

提交示例

git commit -m "feat: add user profile page"
git commit -m "fix(auth): prevent token refresh race condition"
git commit -m "docs: update API reference for v2 endpoints"
git commit -m "refactor(db): extract connection pooling logic"
git commit -m "feat(api)!: change response format for /users"

评审修复提交

处理评审反馈（人工或机器人）的提交应遵循与其他提交相同的规则：提交消息说明改动内容。触发因素——评审者、机器人、轮次编号——属于流程上下文，已记录在 PR 讨论串中，出现在 git log 里只会造成干扰。

干扰信息（切勿使用）	有效信息
fix: coderabbit round 2 fixes	fix: guard nil user in session refresh
fix: address PR review feedback	fix: close file handle on early return
chore: apply copilot suggestions	refactor: dedupe retry logic across fetchers

一轮评审可能产生不同类型的提交——按改动拆分，而不是按轮次拆分。

PR/MR 标题示例

提供方	创建 PR/MR 时使用的标题
GitHub	gh pr create --title "feat: add dark mode" --body "..."
GitLab	glab mr create --title "feat: add dark mode" --description "..."