Community编程与开发github.com

gitmoji

编码技能。使用 Gitmoji Triangle 约定(emoji 对、工单、作用域、摘要)编写 Git 提交,并将暂存的修改拆分为每个提交一个决策。

gitmoji 是什么?

Gitmoji 是一个用于 Claude Code 的技能,它强制执行一套结构化的 Git 提交消息约定,称为“Triangle 提交”。该技能确保每个提交代表一个单一的、可审查的决策,使用特定的 emoji 对来标记变更区域(如 `🧩` 表示代码库)、行为或意图(如 `👔` 表示业务决策)、修饰符(如 `🧪` 表示实验性更改)、工单号和作用域。它提供了一个 `gitmoji` CLI 命令,用于引导用户完成 emoji 选择、检查提交消息格式,并通过脚本集成到提交钩子中。该技能旨在减少提交中的歧义,使代码审查更容易,并自动化生成一致的变更日志。它支持在 Claude Code 中通过 `gitmoji check` 和 `gitmoji staged` 等命令进行交互式规划,并生成包含模型、工具链和合作者信息的签名。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/D1no/gitmoji/tree/HEAD/skills/gitmoji

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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

这些是提示,而不是需要填满的堆栈。仅在工单为以下问题提供了答案时才规划提交:

  • 业务做出了什么决策(👔),以及随着时间的推移会发生什么(⛓️)?
  • 在尝试某个步骤之前拒绝什么(🛡️)?当步骤失败时,它如何恢复,报告什么错误代码,以及用户会被告知什么(🥅)?
  • 各部分之间协定了什么形状(🏷️),以及存储了什么(💾)?
  • 用户看到和做了什么,他们在哪个提交中首次获得这些功能(✨)?
  • 我们如何知道用户在真实产品中成功完成了流程(✅,自己的提交,在产品可以以该方式运行后添加)?

当流程尚无法运行时,先交付功能并在工单上说明其 ✅ 尚未完成。不要为了填补空白而在较小的检查项上使用 ✅;那应该使用 ☑️。

在规划新的端点、存储或策略之前,检查是否存在所有者。如果缺少产品决策并且会影响发布内容,请记下问题并询问。不要在提交内部解决此问题。

一个包含单一决策、其唯一调用者和所需检查的功能,应作为一个提交。仅在工单包含审阅者可以单独接受的多个决策时,才规划更多行。工单从未要求过的行过于细化。

在每个提交之前:四个问题

  1. 更改属于或涉及哪个区域? 测试、文档和测试区采用其所属事物的区域。
  2. 现在有什么不同,或者您做了什么? 如果提交更改了承诺的内容,请命名行为(名词)。否则命名意图(动词)。
  3. 工作是否尚未确定? 只有在这种情况下,才添加第三个 emoji:🧪 试验性,🚧 临时性,💥 消费者必须适应。试验性提交在每个提交上都保留 🧪,直到 🏁(保留)或 ⚰️(放弃),并且在此之前,任何已确定的工作都不能依赖于它。按照工单选择的路线进行构建不是试验。
  4. 哪个工单? 使用仓库的工单格式。只有自动化任务才使用 —。

然后运行 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: <您想表达的内容>,并告知用户。遗漏是词汇表得以完善的方式。

相关技能