Triangle 提交
一个提交主题的格式如下:
<区域><行为或意图>[修饰符] <工单> (<作用域>): <摘要>
🧩👔 #412 (server): 允许在拒绝后 30 天内上诉
🎨💄 — (tokens): 从 Figma 获取新的色调
Emoji 是行的第一个字符,周围没有任何其他内容。最后一个示例是由自动化任务创建的提交:它没有工单,因此使用了长破折号。
词汇量很大,但您无需全部记住。gitmoji 命令会分小块提供。只需阅读您需要的那部分。
命令
使用 gitmoji 命令。如果它不在 PATH 中,请阅读该技能文件夹中的 references/vocabulary.txt 以获取完整词汇表,并告知用户该命令缺失。
| 何时使用 | 运行命令 |
|---|---|
| 您需要区域列表 | gitmoji guide areas |
| 您知道区域 | gitmoji guide 🧩(任何区域 emoji 或名称) |
| 区域指南中没有合适的选项 | gitmoji guide groups,然后选择一个分组:gitmoji guide "repair" |
| 两个条目似乎都合适 | gitmoji guide 🛡️,或分组:gitmoji guide "protection" |
| 工作是试验性的、临时性的或破坏性的 | gitmoji guide modifiers |
| 您需要作用域名称 | gitmoji guide scopes |
| 您即将编写摘要或正文 | gitmoji guide message |
在 git commit 之前 | gitmoji staged,然后对第一行运行 gitmoji check -m '<subject>',或对整个消息运行 gitmoji check <file> |
您键入了短代码,例如 :jigsaw::necktie: | 无需操作:钩子会自动为您写入 emoji |
| 您正在撤销一个提交 | git revert <commit>;Git 自己的第一行保持不变 |
| 钩子拒绝了提交主题 | 阅读其消息;它会指出需要修复的内容 |
| 您希望在分支合并前审查其提交 | gitmoji history trunk..HEAD(目标分支,然后是您的分支) |
| 钩子提示仓库已采用另一个版本 | 阅读其给出的地址处的变更说明,并在更改设置前告知用户 |
在编写代码之前:规划提交
阅读工单并列出您预计会创建的提交主题。每个提交代表一个审阅者可以独立接受的决策,并且每个决策都是工单所要求的内容。每个提交的作用域是拥有该决策的包(gitmoji guide scopes)。
这些是提示,而不是需要填满的堆栈。仅在工单为以下问题提供了答案时才规划提交:
- 业务做出了什么决策(
👔),以及随着时间的推移会发生什么(⛓️)? - 在尝试某个步骤之前拒绝什么(
🛡️)?当步骤失败时,它如何恢复,报告什么错误代码,以及用户会被告知什么(🥅)? - 各部分之间协定了什么形状(
🏷️),以及存储了什么(💾)? - 用户看到和做了什么,他们在哪个提交中首次获得这些功能(
✨)? - 我们如何知道用户在真实产品中成功完成了流程(
✅,自己的提交,在产品可以以该方式运行后添加)?
当流程尚无法运行时,先交付功能并在工单上说明其 ✅ 尚未完成。不要为了填补空白而在较小的检查项上使用 ✅;那应该使用 ☑️。
在规划新的端点、存储或策略之前,检查是否存在所有者。如果缺少产品决策并且会影响发布内容,请记下问题并询问。不要在提交内部解决此问题。
一个包含单一决策、其唯一调用者和所需检查的功能,应作为一个提交。仅在工单包含审阅者可以单独接受的多个决策时,才规划更多行。工单从未要求过的行过于细化。
在每个提交之前:四个问题
- 更改属于或涉及哪个区域? 测试、文档和测试区采用其所属事物的区域。
- 现在有什么不同,或者您做了什么? 如果提交更改了承诺的内容,请命名行为(名词)。否则命名意图(动词)。
- 工作是否尚未确定? 只有在这种情况下,才添加第三个 emoji:
🧪试验性,🚧临时性,💥消费者必须适应。试验性提交在每个提交上都保留🧪,直到🏁(保留)或⚰️(放弃),并且在此之前,任何已确定的工作都不能依赖于它。按照工单选择的路线进行构建不是试验。 - 哪个工单? 使用仓库的工单格式。只有自动化任务才使用
—。
然后运行 gitmoji check -m '<subject>'。
在暂存之前,以不相关人员的视角阅读更改。凡是无法从代码中看出原因的地方,请在代码旁边添加注释:为什么采用这种方式、哪些内容不得更改、值来自何处。说明原因,而不是代码的作用。注释几乎不花费任何成本,但可以为下一位阅读者(可能是人、初级开发人员或没有您上下文的其他 AI 代理)节省猜测时间。
当一对 emoji 不适用时
这是一个需要重新审视的信号,而不是选择最接近的标签。
- 当两个标签都适用时,确定审阅者现在可以接受什么以及可以推迟什么。如果这两个决策可以不同,并且保留的内容仍然可以独立工作,则进行拆分。按路径或块暂存(
git add -p)。 - 当唯一调用者、其连接和所需的拒绝检查都没有自己的承诺时,将它们保持在一起。根据其关键点标记提交;其余部分附带。
gitmoji staged报告两个作用域:提出相同的问题。如果更改只有整体才有意义,例如一种形状在两种语言中镜像,则将其保持在一起,并命名拥有该决策的包。- 由主要更改强制要求的部分附带:其类型、测试、故事、锁文件。
每个提交必须仍然能够单独构建并通过测试。如果拆分会导致构建失败,则将强制要求的部分保持在一起,并在正文中说明。
编写提交
- 摘要: 系统现在做什么,使用领域术语,以小写动词开头。整行(包括 emoji、工单和作用域)长度不超过 140 个字符,越短越好;
gitmoji check -m '<subject>'会在您提交前为您计算长度。不要包含文件名、工单编号或“如何”。 - 描述: 您编写的每个提交都有描述,并且钩子会拒绝没有描述的提交。只有标记(
🔖、🔺)、自动化任务创建的提交以及 Git 自己生成的消息不需要描述。在第一行下面,空一行,然后说明更改的原因:理由、为什么选择这种方式而不是显而易见的方式,或者您选择的值。通常一两行就足够了;最多六行。将工单引用放在句子中(例如,“有关决策,请参阅 #42”)。当有人编辑提交时,Git 可能会删除以#42开头的行。不要重复 diff、列出文件或描述您的过程。 - 使用 Emoji,而不是短代码。 只提交 emoji 字符。
谁创建了提交
切勿将自己添加为作者或共同作者。 不要添加 Co-Authored-By: 行,不要在 git config user.* 或 --author 中设置 AI 代理身份。作者是负责人,钩子会拒绝 AI 代理作为作者。某些工具会在未经请求的情况下为自己添加共同作者行;当钩子因此拒绝提交时,请删除该行并重新提交。
相反,在正文末尾添加一个空行和一个签名,说明提交中涉及的内容:
_
example-model (high), editor
Claude Code (example-session)
子代理:2 × example-helper (medium)
团队:reviewer, tester
研究:3 次搜索,12 个页面
前三行始终存在。后三行仅在适用时出现。提交完成后,钩子将下划线替换为 △ `<version>` ,因此存储的签名如下所示:
△ `1.2.3`
example-model (high), editor
Claude Code (example-session)
编写下划线;切勿自己编写 △ 行。钩子会用此签名结束每条消息,包括人工编写的消息,此时签名只有这一行。gitmoji history 读取签名以判断哪些提交使用了哪个版本。
项目可以在 [rules] 下设置 signature = "agents",以在支持的 AI 代理会话运行提交钩子时要求提供模型和工具链行。人类可以仅使用普通描述进行提交。发布标记和 Git 生成的消息保持其现有的豁免。
| 行 | 含义 |
|---|---|
_ | 签名从此处开始。钩子将其转换为 △ `<version>` 。 |
| 模型行 | 模型及其工作量。逗号后面是您的名字,仅当有人为您提供了名字时才需要。 |
| 工具链行 | 工具链以及(括号内)会话 ID(如果有)。 |
子代理: | 有多少个子代理参与了此提交的部分工作,按模型和工作量列出。 |
团队: | 您为此提交交换过消息的其他 AI 代理。 |
研究: | 为此提交进行的网络搜索、页面阅读和文档查找。 |
切勿凭记忆编写这些内容。 运行该技能文件夹中 scripts/ 目录下适用于您的工具链的脚本,并粘贴其输出。路径是相对于本文件所在的文件夹,无论技能安装在何处:
python3 scripts/claude-code.py
在 Claude Code 中,该文件夹是 ${CLAUDE_SKILL_DIR}。该脚本读取工具链自身对会话的记录。如果您的工具链在那里没有脚本,scripts/README.md 说明了如何一次性创建并添加一个。如果找不到任何记录,脚本会输出 unknown。仓库可能会要求您省略某一行,例如会话 ID;其自身的说明会提示。
如果会话跨越多个任务或仓库,请对照此提交检查可选的 activity 行。仅保留您可以归因于此提交的贡献。
正文可能包含的行
🩹需要Limitation: <依赖无法执行的操作>.📥需要Source: <来源的运行、工具或系统>.🏁和⚰️说明决定因素。🐛可以命名原因:Broken-by: <sha>.
升级 Gitmoji 时
CLI、技能和词汇表共享一个版本号。当仓库的设置指定的版本与命令所说的版本不同时,钩子会发出警告。告知用户,并阅读警告中给出的地址处的变更说明。当用户想要新版本时,在设置的 [vocabulary] 下设置它,并单独提交该更改,版本号放在反引号之间:
🔺 gitmoji `<version>`: <此仓库的变更>
除非用户要求,否则不要重写已共享的历史记录:根据旧规则创建的提交可以保持原样。gitmoji history --unmigrated 显示哪些提交当前无法通过验证。更改固定版本后运行 gitmoji init 以刷新已安装的技能和受管理工作流。
合并拉取请求并升级历史
启用 PR 标题工作流 并选择 拉取请求标题和描述 作为默认合并消息。编写人工标题。Gitmoji 会在提交更改时维护其 emoji 前缀。使用 创建合并提交 并采用建议的消息。GitHub 会保留创作的提交并附加集成的 PR 编号。
对于现有历史,请使用 升级指南 和已安装的 scripts/gitmoji-upgrade-history.py。在创建本地候选版本之前检查 dry run 结果。链接需要证据证明哪个 PR 已合并。替换共享分支是一个需要仓库所有者独立决策的事项。
Git 生成的消息
合并可以有任意标题。钩子会在待处理的合并期间保留 Git 的消息文件,并且 gitmoji history 会通过其多个父提交来识别存储的合并。仅包含文本的 check -m 只能处理主题。它能识别常见的 Git 分支、标签和提交合并标题、GitHub 拉取请求合并标题、编号的 Merge #N 标题、引用的 Git revert 和 reapply 主题、带标题的编号 Revert #N 和 Reapply #N 标题、Git 的默认 squash 日志标题以及自动压缩前缀 fixup! 、squash! 和 amend! 。
使用自定义 PR 标题的 squash 合并会产生一个普通的单父提交。Cherry-pick 和 rebase 也可能携带普通的主题。像检查其他创作的提交一样检查这些提交。PR 编号本身并不标识一个合并。
在采用期间,项目可以在 gitmoji.toml 中设置 [rules] → untagged = "warn" 以接受普通主题并标记它们以供审查。默认值为 "error"。设置为 "off" 时,缺失标签会被静默接受。其他检查仍然适用。在您的分支上使用 gitmoji history trunk..HEAD 查找需要在共享之前重新措辞的主题。历史记录始终严格检查未标记的主题。
当没有合适的选项时
不要强行使用某个条目。使用最接近的诚实选项,添加一行正文 Miss: <您想表达的内容>,并告知用户。遗漏是词汇表得以完善的方式。