SuperAPI AI 工具集

git-clean-worktrees

编程与开发

查看项目

更新于 11-05 16:19

技能介绍

用途

git-clean-worktrees 用于系统性地查找并移除那些工作内容已经存在于主分支(main)上的 Git 工作树。它解决的核心问题是:在功能开发期间创建的工作树,在分支合并后并不会自动消失,仍然保留着分支检出状态,其内部的 git status 会显示“已修改”文件,但这些改动实际上早已提交到 main。工作树因此处于过时状态,却看起来仍在活跃使用,容易让人对哪些内容已合并、哪些未合并产生困惑。

主要能力

该技能按顺序执行多项检查,只要满足任一条件即判定工作树可安全移除:

  • 检查 A:分支已合并到 main。使用 git branch --merged main | grep -q <branch-name>,若分支出现在 --merged 结果中,说明其所有提交都可由 main 到达,可安全移除。
  • 检查 B:squash 合并。squash 合并不会出现在 --merged 中,因为 Git 看到的提交哈希不同。通过比较树来判断分支改动是否已在 main 上:git diff main...<branch-name> --stat,若无输出(空 diff),说明分支内容与 main 完全一致,可安全移除。
  • 检查 C:工作树有未提交改动但与 main 一致。先列出工作树中的未提交改动 git -C <worktree-path> status --porcelain,再对每个修改文件检查 main 是否已包含这些改动 git diff main -- <file-path>。若工作树中每个修改文件都与 main 上的内容一致,则该工作树已过时,可安全移除。

若以上检查均不通过,说明工作树含有真正未合并的工作,技能会将其标记出来提醒用户注意,而不会移除。

使用方式

技能按以下步骤执行:

  1. 列出所有工作树:git worktree list。识别主工作树(仓库根目录),它绝不能被移除;其余均为清理候选。若只有主工作树,则报告“未发现次级工作树”并停止。
  2. 对每个次级工作树,按上述检查 A、B、C 的顺序判断是否过时。
  3. 在行动前展示发现结果,给出清晰摘要,包括可安全移除的条目及其原因(分支已合并、空 diff、或改动与 main 一致),以及需要关注(未合并工作)的条目。
  4. 移除已确认安全的工作树:git worktree remove --force <worktree-path>。使用 --force 是必要的,因为 Git 会认为该工作树的分支存在本地修改(尽管这些改动已在 main 上),这正是本技能的意义所在——我们已验证工作是安全的。
  5. 清理关联分支:移除工作树后,若本地分支已合并则删除:git branch -d <branch-name>。使用小写 -d(安全删除,未合并时会拒绝)。若 -d 因 Git 不将 squash 合并识别为“已合并”而失败,且步骤 2 的检查 B 已确认 diff 为空,则使用 git branch -D <branch-name>。
  6. 清理工作树元数据:git worktree prune,清理引用磁盘上已不存在工作树的过时管理文件。
  7. 验证干净状态:git worktree list,报告移除了什么、剩余什么。

适用场景

该技能适用于功能分支合并后遗留工作树的清理,尤其是使用 Claude Code 内置工作树(通常位于 .claude/worktrees/<name>)、superpowers 技能(位于 .worktrees/<name> 或 worktrees/<name>)或手动及其他工具创建的工作树。应始终以 git worktree list 作为真实来源,不要假设位置。该技能可与 git-branch-cleanup(在其后运行以清理剩余分支)、using-git-worktrees(创建本技能所清理的工作树)、finishing-a-development-branch(处理活跃工作期间的清理)配合使用;本技能专门处理“忘记清理”的情况。

限制与安全规则

  • 绝不删除主工作树(仓库根目录)。
  • 绝不未经用户明确确认就删除含有真正未合并工作的工作树。
  • 强制移除前始终对照 main 进行验证——验证本身就是安全网。
  • 优先使用 git branch -d(安全),仅在对照 main 确认 diff 为空时才升级为 -D。
  • 如有疑问,展示 diff 并询问用户。