gh-commit

智能 Git 提交

创建格式规范的提交：$ARGUMENTS

当前仓库状态

• Git 状态：!git status --porcelain
• 当前分支：!git branch --show-current
• 已暂存的更改：!git diff --cached --stat
• 未暂存的更改：!git diff --stat
• 最近的提交：!git log --oneline -5

此命令的作用

1. 使用 git status 检查哪些文件已暂存
2. 如果没有暂存文件，则使用 git add 自动添加所有已修改和新增的文件
3. 执行 git diff，了解即将提交的更改
4. 分析差异，判断是否包含多个不同的逻辑更改
5. 如果检测到多个不同的更改，则建议将其拆分为多个较小的提交
6. 对于每个提交（如果未拆分，则为单个提交），使用约定式提交格式创建提交信息

提交最佳实践

• 遵循下文所述的约定式提交规范。

约定式提交 1.0.0

概述

约定式提交规范是一套应用于提交信息的轻量级约定。它提供了一组简单的规则，用于创建明确的提交历史记录，从而更容易基于此构建自动化工具。该约定与 SemVer 相辅相成，通过提交信息描述所做的功能、新增特性和不兼容更改。

提交信息应采用以下结构：

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

提交包含以下结构元素，用于向库的使用者传达意图：

1. fix： fix 类型的提交会修补代码库中的错误（对应语义化版本控制中的 PATCH）。
2. feat： feat 类型的提交会为代码库引入新功能（对应语义化版本控制中的 MINOR）。
3. BREAKING CHANGE： 包含 BREAKING CHANGE: 页脚，或在类型／范围后附加 '!' 的提交，会引入不兼容的 API 更改（对应语义化版本控制中的 MAJOR）。任何 类型 的提交都可以包含不兼容更改。
4. 除 fix: 和 feat: 之外，也允许使用其他 类型。例如， @commitlint/config-conventional（基于 Angular 约定）建议使用 build:、chore:、ci:、docs:、style:、refactor:、perf:、test: 等。
5. 除 BREAKING CHANGE: <description> 之外，也可以提供其他 页脚，并遵循类似 git trailer 格式的约定。

约定式提交规范不强制要求使用其他类型，且这些类型在语义化版本控制中没有隐含影响（除非包含不兼容更改）。可以为提交类型指定范围，以提供额外的上下文信息，并将其放在括号内，例如：feat(parser): add ability to parse arrays。

示例

带描述和不兼容更改页脚的提交信息

feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files

使用 '!' 强调不兼容更改的提交信息

feat'!': send an email to the customer when a product is shipped

使用范围和 '!' 强调不兼容更改的提交信息

feat(api)'!': send an email to the customer when a product is shipped

同时包含 '!' 和 BREAKING CHANGE 页脚的提交信息

chore'!': drop support for Node 6

BREAKING CHANGE: use JavaScript features not available in Node 6.

不含正文的提交信息

docs: correct spelling of CHANGELOG

带范围的提交信息

feat(lang): add Polish language

正文包含多个段落和多个页脚的提交信息

fix: prevent racing of requests

Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.

Remove timeouts which were used to mitigate the racing issue but are
obsolete now.

Reviewed-by: Z
Refs: #123

规范

本文档中的关键词“MUST”（必须）、“MUST NOT”（不得）、“REQUIRED”（必需）、“SHALL”（应）、“SHALL NOT”（不应）、“SHOULD”（建议）、“SHOULD NOT”（不建议）、“RECOMMENDED”（推荐）、“MAY”（可以）和“OPTIONAL”（可选），应按照 RFC 2119 中的说明进行解释。

1. 提交信息 MUST 以类型作为前缀。类型由一个名词组成，例如 feat、fix 等，后接可选的作用域、可选的 '!'，以及必需的结尾冒号和空格。
2. 当提交为应用或库添加新功能时，类型 MUST 使用 feat。
3. 当提交表示修复应用中的错误时，类型 MUST 使用 fix。
4. 类型后 MAY 提供作用域。作用域 MUST 是一个描述代码库某个部分的名词，并用括号括起来，例如 fix(parser):。
5. 描述 MUST 紧跟在类型／作用域前缀后的冒号和空格之后。描述是对代码更改的简短总结，例如：fix: 字符串中包含多个空格时的数组解析问题。
6. 简短描述之后 MAY 添加较长的提交正文，以提供有关代码更改的更多背景信息。正文 MUST 在描述之后空一行开始。
7. 提交正文格式不限，MAY 包含任意数量的、以换行符分隔的段落。
8. 正文之后 MAY 空一行添加一个或多个页脚。每个页脚 MUST 由一个词语标记组成，后接 :<space> 或 <space># 分隔符，再后接一个字符串值（此约定受 git trailer convention 启发）。
9. 页脚标记 MUST 使用 - 替代空白字符，例如 Acked-by（这有助于将页脚部分与多段正文区分开来）。BREAKING CHANGE 除外，它也 MAY 用作标记。
10. 页脚的值 MAY 包含空格和换行符；当检测到下一个有效的页脚标记／分隔符组合时，解析 MUST 终止。
11. 重大更改 MUST 在提交的类型／作用域前缀中标明，或作为页脚条目标明。
12. 如果作为页脚标明，重大更改 MUST 由大写文本 BREAKING CHANGE、冒号、空格和描述组成，例如：BREAKING CHANGE: 环境变量现在优先于配置文件。
13. 如果在类型／作用域前缀中标明，重大更改 MUST 通过紧挨冒号之前的 '!' 表示。如果使用了 '!'，页脚部分 MAY 省略 BREAKING CHANGE:，并 SHALL 通过提交描述说明重大更改。
14. 除 feat 和 fix 外，提交信息 MAY 使用其他类型，例如：docs: 更新参考文档。
15. 实现者 MUST NOT 将构成 Conventional Commits 的信息单元视为区分大小写，但 BREAKING CHANGE 除外，它 MUST 使用大写。
16. 在页脚中用作标记时，BREAKING-CHANGE MUST 与 BREAKING CHANGE 同义。

为什么使用 Conventional Commits

• 自动生成 CHANGELOG。
• 自动确定语义化版本的变更幅度（根据已合并提交的类型）。
• 向队友、公众和其他利益相关者传达更改的性质。
• 触发构建和发布流程。
• 通过让人们浏览结构更清晰的提交历史，降低他们为项目做贡献的难度。

常见问题

在初期开发阶段，我该如何处理提交信息？

我们建议你按照产品已经发布的情况来处理。通常会有人在使用你的软件，即使这个人只是你的软件开发同行。他们会想知道修复了什么、哪些内容会被破坏，等等。

提交标题中的类型应使用大写还是小写？

大小写均可，但最好保持一致。

如果一个提交符合多种提交类型，该怎么办？

尽可能回退并拆分为多个提交。 Conventional Commits 的好处之一，就是能够促使我们创建更有条理的提交和 PR。

这会妨碍快速开发和快速迭代吗？

它妨碍的是无序地快速推进。它能帮助你在多个项目和不同贡献者参与的情况下，长期保持快速推进。

Conventional Commits 会不会让开发者只考虑规范中提供的类型，从而限制他们提交的类型？

Conventional Commits 鼓励我们多创建某些类型的提交，例如修复。除此之外，Conventional Commits 的灵活性允许团队自行设定类型，并随时间推移更改这些类型。

这与 SemVer 有何关系？

fix 类型的提交应对应 PATCH 版本发布。feat 类型的提交应对应 MINOR 版本发布。无论提交类型是什么，包含 BREAKING CHANGE 的提交都应对应 MAJOR 版本发布。

我该如何为 Conventional Commits 规范的扩展（例如 @jameswomack/conventional-commit-spec）确定版本？

我们建议使用 SemVer 发布你对本规范所做的扩展（并鼓励你创建这些扩展！）

如果我不小心使用了错误的提交类型，该怎么办？

如果你使用的类型属于规范，但并非正确类型，例如用 fix 代替 feat

在合并或发布之前，我们建议使用 git rebase -i 编辑提交历史。发布之后，清理方式则取决于你使用的工具和流程。

如果你使用的类型不属于规范，例如用 feet 代替 feat

最糟糕的情况下，即使有一个不符合 Conventional Commits 规范的提交进入代码库，也并非世界末日。这仅意味着基于该规范的工具会忽略这个提交。

所有贡献者都需要使用 Conventional Commits 规范吗？

不需要！如果你使用基于 Git 的压缩合并工作流，主要维护者可以在合并时整理提交消息，不会给临时提交者增加工作量。一种常见的工作流是让 Git 系统自动压缩拉取请求中的提交，并提供表单，让主要维护者填写正确的 Git 合并提交消息。

Conventional Commits 如何处理还原提交？

还原代码可能很复杂：你是在还原多个提交吗？如果你还原了一项功能，下一次发布是否应改为补丁版本？

Conventional Commits 不会专门定义还原行为，而是将其交由工具作者处理，让他们利用 类型 和 页脚 的灵活性来开发还原处理逻辑。

一种建议是使用 revert 类型，并添加引用被还原提交 SHA 的页脚：

revert: let us never again speak of the noodle incident

Refs: 676104e, a215868

标注 AI 辅助代码的作者身份

使用 AI 工具生成代码时，透明地说明作者身份有助于问责、代码审查和审计。使用 Git trailers 在提交消息末尾附加结构化元数据，即可轻松实现这一点。

可以在提交消息中附加一个或多个自定义 trailer，例如：

Assistant-model: Claude Code

由于大多数 Git 工具都要求 Co-authored-by trailer 使用电子邮件地址格式，因此应使用不同的 trailer 键，以免造成混淆，并区分作者身份与辅助关系。

可以在提交消息末尾手动添加 trailer，也可以使用带有 --trailer 选项的 git commit 命令：

git commit --message "Implement feature" --trailer "Assistant-model: Claude Code"

可以使用 git log 命令的 pretty formats 选项来显示 trailer。例如，格式化历史记录可显示每次提交的哈希值、作者姓名和所用的助手模型：

git log --color --pretty=format:"%C(yellow)%h%C(reset) %C(blue)%an%C(reset) [%C(magenta)%(trailers:key=Assistant-model,valueonly=true,separator=%x2C)%C(reset)] %s%C(bold cyan)%d%C(reset)"

2100e6c Author [Claude Code] Test commit 4 (HEAD -> work-item-8)
7120221 Author [Claude Code] Test commit 3
ea03d91 Author [] Test commit 2
f93fd8e Author [Claude Code] Test commit 1
dde0159 Claude Code [] Test work item (#7) (origin/main, origin/HEAD)

重要说明

• 默认情况下，会运行预提交检查（定义在 prek.toml 中）以确保代码质量
  • 重要：不要跳过预提交检查
• 始终标注 AI 辅助代码的作者身份
• 如果已有特定文件处于暂存状态，命令只会提交这些文件
• 如果没有文件处于暂存状态，命令会自动暂存所有已修改和新增的文件
• 提交消息会根据检测到的更改生成
• 提交前，命令会审查差异，以判断是否更适合拆分为多个提交
• 如果建议拆分为多个提交，命令会帮助你分别暂存并提交更改
• 始终审查提交差异，确保提交消息与更改相符