SuperAPI AI 工具集

git-post-merge-cleanup

编程与开发

查看项目

更新于 11-05 16:19

技能介绍

用途

Git Post-Merge Cleanup 用于在一批 PR 合并后,一次性清理本地仓库中积累的残留物:已完全合并到默认分支的本地分支、远端已被删除的远程跟踪引用,以及那些仍显示“已修改”文件但改动其实已在主分支上的工作树。该技能强调扫描成本低,因此始终同时处理这两类对象。

主要能力

  • 刷新远端状态:执行 git fetch origin --prune,避免 GitHub 已删除的分支在本地留下过期的 origin/* 引用。
  • 检测默认分支:不假设默认分支是 main,而是通过 git symbolic-ref -q --short refs/remotes/origin/HEAD 2>/dev/null | sed 's@^origin/@@' 获取;若失败则回退检查本地是否存在 main 或 master,结果作为 $DEFAULT。
  • 扫描并分类分支:交叉引用 git branch -vv、git branch --merged origin/$DEFAULT、git branch -r --merged origin/$DEFAULT、git branch -r --no-merged origin/$DEFAULT,将每个分支归入以下类别:
    • fully-merged-local:已合并的本地分支,可安全用 git branch -d 删除。
    • fully-merged-remote:已合并的远程分支,可安全用 git push origin --delete 删除。
    • orphan-tracking:跟踪的远程已消失且分支未合并,属于未合并工作,标记提醒用户,不删除。
    • in-flight:其他情况,保持不动。
  • 扫描并分类工作树:执行 git worktree list,第一个条目是主工作树(仓库根目录),永远不作为候选。对每个次级工作树分类为:
    • safe-worktree:分支已完全合并到 $DEFAULT,或 squash 合并后与 $DEFAULT 的 diff 为空,或未提交的改动全部与 $DEFAULT 一致。可安全用 git worktree remove --force 移除。
    • unsafe-worktree:确实未合并的工作,标记提醒用户,不移除。
  • 生成合并计划:按类别分组展示,包含数量和原因,例如本地分支、远程分支、工作树、需要关注的项目以及保留的项目。若某类别为空,会明确说明(如“No orphaned branches.”),而不是省略。
  • 确认与执行:默认等待用户确认;--dry-run 仅打印计划后停止;--yes 跳过确认但仍先打印计划。执行顺序为先移除工作树再删除其分支,否则 git branch -d 会因分支被其他工作树检出而拒绝。
  • 输出摘要:最后用 git branch -vv 和 git worktree list 展示最终状态,报告删除的本地分支、远程分支、移除的工作树、标记关注的项目以及剩余内容。

使用方式

该技能通过标志控制行为:

  • --dry-run:扫描并展示计划,但不删除任何内容。
  • --yes:跳过确认提示,但仍先展示计划。
  • 默认(无标志):扫描、展示计划、等待确认。

执行步骤依次为:刷新远端状态、检测默认分支、扫描并分类、展示计划、确认、执行、输出摘要。执行时使用 git worktree remove --force <worktree-path> 移除安全的工作树,使用 git branch -d branch1 branch2 branch3 删除本地已合并分支,使用 git push origin --delete branch1 branch2 branch3 删除远程已合并分支(使用裸名称,去掉 origin/ 前缀),最后执行 git worktree prune 和 git fetch origin --prune 清理元数据与跟踪引用。

适用场景

适用于在批量合并 PR 后需要整理本地仓库的开发者,尤其是当本地存在大量已合并分支、远程已删除但本地仍保留的跟踪引用,以及因 squash 合并而显示“已修改”的工作树时。

限制与安全规则

  • 绝不删除主工作树(仓库根目录)。
  • 绝不删除 $DEFAULT、develop、staging 或 production 分支。
  • 未经用户明确确认,绝不删除有未合并工作的分支或移除有未合并工作的工作树;“needs attention”类别就是信号。
  • 始终优先使用小写 -d 而非大写 -D。除非确认是 squash 合并(与 $DEFAULT 的 diff 为空)或用户明确要求强制删除,否则不使用 -D。
  • 分类是安全网,不要凭肉眼判断。
  • 边界情况:无内容可清理时报告“Already tidy”并停止;远程删除遇到权限错误时清晰报告,建议使用 GitHub UI 或检查权限;--merged 未检测到的 squash 合并由空 diff 检查覆盖;某类别数量超过 20 时全部列出但按前缀分组(如“12 feat/, 5 chore/”)以保持计划可读。