git-worktree-tidy

git-worktree-tidy

用于裸仓库 + 工作树布局的日常维护。获取 origin，清理已消失的分支和孤立工作树，并快进重要的本地分支。

适用场景

用户在基于工作树的仓库中要求“获取并清理”， “清理过期分支/工作树”或“将 main/dev 更新到最新版本”。

硬性规则

• 所有破坏性操作（移除工作树、删除分支）都需要用户确认。列出完整清单并等待确认。
• 未经明确批准，绝不能强制删除含有未提交更改的工作树。单独标记有未提交更改的工作树。
• 更新分支时使用 --ff-only。如果仅快进失败，则停止并询问。
• 分支/工作树管理命令应在 .bare 目录（或仓库根目录）中执行。
• 绝不能仅根据 git rev-list origin/main..<branch> 或 git merge-base --is-ancestor 推断“已合并/已发布”。压缩合并和变基合并会将改动合入一个新的 SHA，因此，已完全发布的分支仍会显示有提交“未在 main 中”，且分支 tip 不是其祖先。将已消失的分支归类为未合并之前，应根据代码托管平台上的 PR 合并状态（步骤 3a）核实其发布状态。

工作流

1) 定位裸仓库根目录

确定裸仓库目录：

• 如果当前工作目录中包含 .bare/，则使用它
• 否则：git rev-parse --git-common-dir

所有分支和工作树管理命令都应在此目录中执行。

2) 获取并清理

git fetch --prune origin

报告清理的内容（已删除的远程跟踪分支、已更新的引用）。

3) 查找过期分支

git branch -vv | grep ': gone]'

收集上游已消失的分支名称。

3a) 核实发布状态（上游已消失 ≠ 已合并）

上游已删除（“已消失”）并不能证明改动已发布，而且 git 的祖先关系在此处并不可靠：压缩合并和变基合并会将改动合入一个新的 SHA，因此，已完全发布的分支仍会显示有提交“未在 main 中”，且分支 tip 不是其祖先。删除之前应通过代码托管平台核实——已消失但未合并的分支是唯一会导致实际改动丢失的分支。

针对每个上游已消失的分支（以下为 GitHub 示例；请替换为对应代码托管平台的 CLI）：

# Was there a merged PR from this head?
gh pr list --state all --head <branch> \
  --json number,state,mergedAt,mergeCommit \
  --jq '.[] | "#\(.number) \(.state) merged=\(.mergedAt // "no")"'

# If merged, confirm nothing was added to the branch AFTER the merge:
# the local tip should equal the PR head at merge.
gh pr view <pr> --json commits --jq '.commits[-1].oid'   # vs: git rev-parse <branch>

对每个已消失的分支进行分类：

• 已合并（已核实） — 存在状态为 MERGED 的 PR，且其 head == 本地 tip → 已发布，可以安全删除。
• 有风险 — 不存在已合并的 PR，或 tip 上的提交日期晚于合并日期（git show -s --format=%ci <tip>）→ 存在尚未发布的实际改动。标记出来；未经明确批准不得删除。

如果 gh/代码托管平台的 CLI 不可用，请说明这一点，并将无法核实的分支视为有风险，而不是假定已合并。

4) 查找过期工作树

git worktree list
git worktree prune --dry-run

将工作树与已消失分支列表交叉核对。检查每个过期工作树是否有未提交更改：

cd <worktree-path> && git status --short

分类：

• 干净 + 分支已消失：可以安全移除
• 有未提交更改 + 分支已消失：标记出来供用户检查
• 可清理的元数据：孤立的工作树条目（目录已不存在）

5) 确认删除

提供汇总表：

Stale worktrees to remove:
  <path> (<branch>) [clean]
  <path> (<branch>) [dirty — N uncommitted changes]

Stale branches:
  <branch>  [merged — PR #N, safe to delete]
  <branch>  [AT RISK — no merged PR / commits after merge; review first]

Prunable worktree metadata:
  <entry>

明确指出有风险的分支，以便用户在了解其发布状态后做决定。继续操作前等待用户确认。

6) 移除过期工作树

针对每个已确认的工作树：

git worktree remove <name>

如果移除失败（存在未提交更改），请报告并跳过，除非用户已批准强制移除。

7) 删除过期分支

git branch -D <branch1> <branch2> ...

8) 清理工作树元数据

git worktree prune -v

9) 更新重要分支

确定哪些分支在 main、dev 或其他重要分支下有专用工作树（用户可能会指定）。针对每个分支：

cd <worktree-path> && git pull --ff-only origin <branch>

如果仅快进失败，请报告分支分叉情况并询问如何处理。

10) 最终状态

显示摘要：已移除的内容、已更新的内容，以及跳过的项目。