Git 批量提交工具

概述

将混合的修改自动拆分为多个聚焦的、逻辑清晰的提交。而不是创建一个包含"更新各种文件"的大提交，而是创建多个清晰的提交，如"docs: 更新 README"、"chore: 更新依赖"、"license: 更新 license 文件"。

与 git-workflow 的职责边界

git-batch-commit 是提交拆分工具，不是完整 Git 工作流控制器。

当用户只是说“把这些改动提交一下 / 拆分提交”，使用本 Skill；当用户说“合并 PR / 拉 PR 到 main / 推送 / 关闭 issue”，同时遵循 git-workflow。

隐私预检与依赖

运行脚本需要 Python 3.10+、Git、PyYAML（缺失时运行 python3 -m pip install PyYAML），并同时安装同级 git-workflow 技能。共享 checker 仅使用 Python 标准库；缺失时失败关闭。

在预览、确认或创建第一笔提交前，检查所有分组最终完整提交说明（含 Markdown 标题/列表提取、Issue 和本地任务引用）、暂存变更路径、完整 blob 和 patch。--yes 只跳过交互确认，--dry-run 也须检查，均不能跳过隐私门禁。任一组失败不创建任何提交，也不输出敏感原文。

逐组提交使用原始暂存 tree 的临时 index，不取消暂存再重新 git add 工作区；部分暂存文件的未暂存改动不会混入。要求已有 HEAD；预检或执行期间 HEAD/index 改变则停止。执行期失败保留已成功本地提交，不自动回滚；发布前仍须 git-workflow 全范围检查。

案号是待核对标记，公开裁判/虚构测试须有依据的精确审查，不允许目录整体忽略或以 --no-verify 替代审查。规则、Git 目录内本地黑名单、精确例外与二进制处理限制见 共享隐私预检。

使用场景

• 用户暂存的文件来自多个类别（文档 + 代码 + 配置）
• 用户希望保持清晰、标准化的提交历史
• 用户提到"批量提交"、"拆分提交"或"整理提交"
• 用户修改了许多文件，希望按逻辑分组

快速开始

方式一：使用交互式脚本

# 首先暂存你的文件
git add file1.py file2.md package.json

# 运行交互式批量提交工具（需要确认）
python3 skills/git-batch-commit/scripts/interactive_commit.py

# 或使用 --yes 参数自动确认（适用于非交互式环境）
python3 skills/git-batch-commit/scripts/interactive_commit.py --yes

# 使用 --dry-run 仅查看分组，不实际提交
python3 skills/git-batch-commit/scripts/interactive_commit.py --dry-run

# 这组提交关联 GitHub Issue #13：每个标题追加 (#13)，正文写 Refs #13
python3 skills/git-batch-commit/scripts/interactive_commit.py --issue 13

# 这组提交关联项目本地任务，不误关 GitHub Issue
python3 skills/git-batch-commit/scripts/interactive_commit.py --local-ref "project-task Issue #13"

命令行参数：

• --yes, -y：跳过交互式确认，自动创建提交
• --dry-run：仅显示分组建议，不实际创建提交
• --issue N：关联 GitHub Issue，提交标题追加 (#N)，正文写 Refs #N
• --local-ref "..."：关联项目本地任务，如 project-task Issue #13，只写 Refs: ...，不会关闭 GitHub Issue

方式二：手动分类

python3 skills/git-batch-commit/scripts/categorize_changes.py
python3 skills/git-batch-commit/scripts/categorize_changes.py --json

提交分类

支持类型：docs, feat, fix, refactor, style, chore, license, config, test

完整定义和检测逻辑详见 references/commit-types.md

技能核心文件的特殊处理

重要规则：SKILL.md 虽然是 Markdown 格式，但它是技能的核心功能文件，不应归类为 docs 类型。

判断依据：

• 如果修改的是定义行为/功能的文件（如 SKILL.md、.py、.ts），视为代码变更
• 如果修改的是记录/说明性质的文件（如 README.md、CHANGELOG.md），视为文档变更

同 Skill 内伴随变更合并规则

核心原则：同一 Skill 内的功能变更及其直接关联的配套文件更新，应合并为一条提交，不要按文件类型拆分。

具体规则：

• 当 SKILL.md 有功能变更（feat/fix/style），同 Skill 下的 CHANGELOG.md 更新应合并进同一条提交，不单独拆出 docs 提交
• 同理，版本号变更、配置微调（如删除 .clawhubignore）等配套小改动也一并合并
• 判断标准：这些文件变动是否由同一个功能变更引起？如果是，就是一条提交
• 只有当 CHANGELOG 独立更新（如补录历史版本）且无对应功能变更时，才单独使用 docs 类型

提交信息格式

所有提交遵循格式：

<类型>: <标题>

<正文描述>

重要规则：每个提交必须包含正文（body），不能只有标题。 正文用于补充变更的具体内容和原因，方便后续追溯。

使用英文前缀加中文内容，确保 GitHub 能识别并显示彩色标签。完整示例见 references/conventional-commits.md

Multi-Module/Multi-Skill 仓库规则：

• 描述中应包含模块名称：docs: course-generator 更新 CHANGELOG
• 如果一次修改涉及多个模块，必须按模块分别提交
• 描述中的模块名称使用原始英文名称，不要翻译

Issue / Task 引用规则：

• 若一组批量提交关联 GitHub Issue，使用 --issue N。每个提交标题会包含 (#N)，正文写 Refs #N。
• 本 Skill 不生成 Closes #N。是否关闭 GitHub Issue 属于 git-workflow 的判断范围。
• 若编号来自项目本地任务源而非 GitHub Issue，使用 --local-ref "project-task Issue #N" 或项目约定的等价引用，不要写 Closes #N。
• PR 合并提交的 (#PR编号) 规则不由本 Skill 决定，遵循 git-workflow。

工作流程

1. 暂存文件 - 使用 git add 正常暂存
2. 运行交互式脚本 - 全部分组与暂存内容预检通过后查看分类结果
3. 审核 - 检查提议的提交分组
4. 确认 - 创建提交或取消以调整
5. ClawHub 同步检查 - 仅当 skills/skill-publish-sync/ 存在时执行，详见 references/skill-publish-sync-check.md。不存在则静默跳过
6. Subtree 推送检查 - 先查本技能 config/subtree-repos.yaml 是否登记了当前仓库（按仓库定制配置路径/前缀/触发时点/推送命令；PR 流程仓库登记 trigger: after-merge-to-main，合入 main 后才提示）；未登记则回退默认检测 skills/subtree-publish/config/subtree-skills.json。均未命中则静默跳过，详见 references/subtree-push-check.md
7. 完成 - 获得清晰历史的聚焦提交

所需权限与能力边界

本技能核心职责是 Git 提交拆分，但提交完成后可能触发以下可选的后续动作。这些动作均超出"仅提交"的最小职责，且只有在满足触发条件时才会发生，并必须经用户显式确认：

发布到外部平台（ClawHub / SkillHub）

• 仅当仓库内存在 skills/skill-publish-sync/，且本次提交涉及 skills/<skill-name>/ 下的版本更新/新增技能、且该技能在 sync-allowlist.yaml 白名单中时，才会提示用户是否同步。
• 每个发布动作前都会向用户确认（是否将其加入白名单并同步？，选项 y/n/s）；未确认不会执行 clawhub publish / skillhub publish。
• 发布会把技能内容上传到 ClawHub/SkillHub 平台；发布前检查临时目录不含 .env、密钥等敏感文件。
• 用户选择同步后，会修改 skills/skill-publish-sync/config/sync-allowlist.yaml 与 sync-records.yaml（仓库状态变更）。

推送 subtree 独立仓库

• 触发检测支持两种来源：①本技能 config/subtree-repos.yaml 按仓库登记（config_path 定制登记清单路径、prefix 定制子目录前缀、trigger 定制触发时点、push_command 定制推送命令）；②未登记仓库走默认路径 skills/subtree-publish/config/subtree-skills.json（提交后即提示）。
• trigger: after-merge-to-main（PR 流程仓库，如 dsh-plugins）：批量提交发生在特性分支时不提示，待 PR 合入 main 后再提示——防止把未合并分支内容派发到独立镜像。
• 检测命中已注册子目录、且对应 remote 可用（默认 <name>-standalone，登记清单可按项覆盖）时才提示。
• 推送动作需用户确认，不会自动执行。

本地命令执行

• 本技能通过 subprocess 调用 git（暂存/提交/查看 diff）与 clawhub/skillhub（仅用户确认发布后）等外部命令。命令以参数数组拼接，不经过 shell 字符串拼接。

文件访问

• 读取 git diff/git status 输出、skills/*/SKILL.md frontmatter、skill-publish-sync/config/sync-allowlist.yaml 与 sync-records.yaml。
• 修改上述 allowlist/records 文件（仅用户确认后）。

若你只希望"纯粹提交、绝不触发任何发布/推送提示"，请先移除或重命名仓库中的 skills/skill-publish-sync/、skills/subtree-publish/config/subtree-skills.json，并删除本技能 config/subtree-repos.yaml 中该仓库的登记——这两个步骤会静默跳过。

资源文件

scripts/

• categorize_changes.py - 分析 git diff 并按类别分组文件
• generate_commit_message.py - 生成约定式提交信息
• interactive_commit.py - 批量提交的主交互式工具

references/

• commit-types.md - 详细的类别定义和检测逻辑
• conventional-commits.md - 提交信息规范
• skill-publish-sync-check.md - ClawHub 同步检查详细流程（工作流第5步）
• subtree-push-check.md - Subtree 推送检查详细流程（工作流第6步）