用途
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:其他情况,保持不动。
- fully-merged-local:已合并的本地分支,可安全用
- 扫描并分类工作树:执行
git worktree list,第一个条目是主工作树(仓库根目录),永远不作为候选。对每个次级工作树分类为:- safe-worktree:分支已完全合并到
$DEFAULT,或 squash 合并后与$DEFAULT的 diff 为空,或未提交的改动全部与$DEFAULT一致。可安全用git worktree remove --force移除。 - unsafe-worktree:确实未合并的工作,标记提醒用户,不移除。
- safe-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/”)以保持计划可读。