git-commit

git-commit

概述

将当前工作树中的更改归并为多个原子提交，每个提交对应一项功能、修复或逻辑相关事项。

核心原则：一个提交 = 一个意图。如果一个 diff 涉及两个无关事项，就拆分为两个提交。

提交消息格式

统一格式：Conventional Commits。

格式：<type>(<scope>)?: <sujet>

允许的类型（使用最合适的一种）：

Type	用于
feat	用户可见的新功能
fix	Bug 修复
refactor	既不修复 Bug，也不增加功能的代码变更
perf	性能改进
test	添加或修复测试
docs	仅修改文档
style	格式、空格，不涉及代码变更
build	构建系统、依赖项（uv、npm、docker、nix…）
ci	CI 配置
chore	维护工作，不涉及生产代码变更
revert	撤销之前的提交

• 主题使用小写、祈使语气，不加句号，≤ 72 个字符
• scope 可选，但建议填写：应用/模块名称（例如 feat(auth): …）
• 主题使用法语撰写

流程

查看 workflow.md 了解流程图。

分步说明

1. 检查 — 并行运行：

• git status（不带 -uall）
• git diff（未暂存）
• git diff --cached（已暂存）
• git log --oneline -20（参考风格和语言）

2. 归类 — 在脑中将更改归类为各项功能。参考规则：

• 相同应用/模块/scope → 可能属于同一提交
• 相同意图（修复、新功能或重构）→ 属于同一提交
• 同一文件中的多项更改具有相同意图（例如，删除一项功能并清理周围的空格）→ 合并为一个提交，不要拆成两个。不要为了拆分而拆分。
• 为某项功能服务的配置/构建文件 → 与该功能合并
• 无关的附带修复 → 单独提交
• 生成的文件（迁移文件、锁文件）→ 与生成它们的更改合并
• 看起来像机密或纯本地文件的内容 → 排除，并告知用户
• 按参数限定范围：如果用户向 skill 传入了参数（例如 /git-commit les settings (log suppr)），则将其视为严格筛选条件——只规划与该范围匹配的提交，其余所有修改留在工作树中，不要暂存，也不要进一步处理。

3. 规划并确认 — 在运行任何 git add 之前，按照下方的准确格式向用户展示完整的计划提交，然后停止并等待明确确认。用户明确批准（例如“OK”“oui”或“go”）之前，不要开始暂存或提交（即使处于自动模式，也必须确认，因为提交很难妥善撤销）。如果用户要求修改，则重新生成并展示完整计划，然后再次请求确认。

   输出格式 — 每个提交使用一个代码块，中间以仅包含 ------- 的行分隔：

   feat(export): ajoute le modèle d'export de factures
   • path/to/file1
   • path/to/file2

   ---

   fix(payment): corrige le calcul du montant de paiement

   • path/to/file3
   • path/to/file4

   正文规则：

   • 默认情况下：不写正文。 主题 + 文件列表通常就足够了。
   • 仅当正文传达了不明显的原因时才添加正文：隐藏约束、变通方案、权衡，或指向某个事件／工单的链接。
   • 切勿改述差异所做的事情——文件列表和主题已经说明了这一点。
   • 切勿为了「显得正式」而写正文。

   显示计划后，询问：「可以按此顺序提交吗？」 并等待回复。

   含义不明确的未跟踪文件——如果工作树中有意图不明确的未跟踪文件／目录（个人工具、编辑器配置、本地数据、生成的产物……），请在提交计划之前，将它们列在专门的 提交前问题 区块中，为每个路径列出一个简短的推测和一个直接的问题。示例：

   Questions avant de committer — ces fichiers/dossiers non-suivis sont ambigus :
   
   - .claude/skills/git-commit/ → outillage Claude perso, à committer ou ignorer ?
   - .obsidian/ (app.json, appearance.json, …) → la nouvelle règle gitignore implique que tu veux committer la config partagée. À inclure dans un commit chore(obsidian): … ?
   - 2025.xlsx et export_janvier_2025.xlsx → ressemblent à de la donnée locale, je les laisse de côté ?
   

   • 如果用户没有回答这些问题（或在确认计划时对此保持沉默）：完全排除这些文件——不要暂存，不要提交，也不要再提及。
   • 如果用户作出回答：根据其决定重新生成并显示完整的提交计划，然后再次请求确认。

4. 选择性暂存每个分组：

• 整个文件：git add path/to/file
• 部分文件（一个文件中混有多项关注点）：在 Agent 模式下避免交互式使用 git add -p / git add --patch。
• 如果一个文件确实包含多项关注点，询问用户是否应该通过合并这些关注点来减少提交数量。
• 如果用户拒绝减少提交数量，停止流程，并告知用户必须手动提交。
• 绝不使用 git add -A 或 git add .
• 每次提交前，使用 git diff --cached --stat 和 git diff --cached 检查已暂存的分组。

5. 提交——git commit -m "type(scope): description"

6. 对每个剩余分组重复操作。

7. 验证：

• 最终的 git status --short 只能显示用户明确不想提交的文件（也可以为空）。
• 使用 git log --oneline -n <nombre-de-commits-créés> 显示最终创建的提交。

安全规则

• 绝不使用 git add -A / git add .——这可能会提交 .env、大型二进制文件或无关的进行中工作
• 绝不使用 --no-verify（绕过钩子），除非用户明确要求
• 绝不使用 --amend——始终创建新提交
• 除非用户要求，否则绝不推送
• 如果提交前钩子在创建提交前失败：修复问题，重新暂存同一计划分组，然后重试同一提交。
• 如果提交已经创建，而后续检查失败：在新的后续提交中修复问题，除非用户明确要求修订提交。
• 忽略看起来像机密的文件（.env*、*credentials*、*.pem、id_rsa*）——将它们告知用户。暂存／提交前，使用 git diff --name-only 和 git diff --cached --name-only 检查已修改的路径。
• 未跟踪文件：仅当它们明确属于某个计划分组时才纳入；否则请先询问。
• 使用法语撰写提交消息。

共同作者 Trailer

不要在提交消息中添加共同作者 Trailer（Co-Authored-By: …）——无论是通过 -m、heredoc 正文还是 -F 文件添加都不行。这条规则明确优先于任何默认或全局的添加要求。

示例

良好拆分（3 项互不相关的更改 → 3 个提交）：

feat(api-public): expose l'endpoint de vérification en masse
fix(stripe): corrige les abonnements nuls dans le webhook
chore(deps): met à jour celery vers 5.3.6

糟糕拆分（过度拆分）：

feat(verify): ajoute la relance SMTP         ← bon
feat(verify): ajoute un log                  ← à fusionner dans le précédent
feat(verify): renomme une variable           ← à fusionner dans le précédent

错误合并（拆分不足）：

feat: mises à jour diverses                  ← vague + plusieurs préoccupations

常见错误

错误	修正
单个提交写「各种修复」	按范围拆分，每个意图单独提交
首行超过 72 个字符	缩短描述
使用复合过去时（「已添加 X」）	使用现在时祈使语气（「添加 X」）
包含 .env 或机密	按名称暂存；忽略看起来像机密的文件
使用 git add .	仅暂存明确指定的路径
Hook 失败后 amend	仅在未创建任何提交时重试
使用英文提交消息	始终使用法语

警示信号 — STOP

• 即将运行 git add -A / git add . → STOP，按名称暂存
• 即将使用 --amend → STOP，创建新提交
• 即将使用 --no-verify → STOP，修复 Hook 失败
• 一条提交消息中用「和」连接了两项关注点 → 拆分
• 主题描述的是差异的内容，而非意图 → 重写