Git worktree清理已删除分支留下的工作树的实现方法

Git 分支删掉后，worktree 仍然出现在列表里，并不一定代表 Git 出错。先看工作树目录是否还存在：目录还在时应走 git worktree remove，目录已经被手动删除时才适合用 git worktree prune 清理失联的管理元数据。这样既不会误删同仓库里的有效工作树，也能让列表恢复干净。

官方文档：https://git-scm.com/docs/git-worktree

步骤1：在终端列出 worktree 并确认残留类型

在仓库根目录打开终端，进入 Git 客户端的“仓库根目录 → 工作树检查”入口，执行下面的命令。这里的入口指当前仓库目录，不是某一个已经删除的分支目录。

# 用机器可读的字段查看每个工作树，便于逐项核对路径
git worktree list --porcelain
# 只查看当前分支和工作区状态，不要先执行清理
git status --short --branch

重点看 worktree、HEAD 和 branch 三类字段，再到文件管理器或终端检查 worktree 后面的路径。分支被删除但目录仍在，属于“有效工作树需要处理”；目录已经不存在，才是“失联元数据候选”。

步骤2：对仍存在的工作树走 remove 路径

如果目标路径仍存在，先在该目录检查未提交文件、未推送提交和正在使用的 IDE 进程。Git 的 linked worktree 仍是一个真实工作区，不能因为它对应的分支已经删除，就把目录当成垃圾直接清空。

在“终端 → 仓库根目录 → 工作树移除”路径执行：

# 把路径替换成步骤1确认过、且准备移除的工作树
git worktree remove ../feature-a
# 若工作树有明确要放弃的未提交内容，才显式使用强制参数
git worktree remove --force ../feature-a

优先使用不带 --force 的命令。若命令拒绝执行，先保存改动或确认确实可以丢弃，再决定是否强制移除。成功后，状态栏应不再显示该路径；不要把 git branch -D 当成工作树清理命令，两者处理的是不同对象。

步骤3：预览并清理已删除目录的管理元数据

如果步骤1确认工作树目录已经不存在，在“终端 → 仓库根目录 → Worktrees → 清理预览”路径先执行预览。-n 只演练将被删除的管理文件，-v 让输出带上处理信息。

# 先预览 Git 认为已经失联的 worktree 管理元数据
git worktree prune -n -v
# 逐项确认路径确实已删除后，再执行实际清理
git worktree prune -v

预览列出的应是已经不存在的工作树路径，而不是仍在使用的目录。看到有效路径时不要继续执行，回到步骤1检查路径拼写、挂载盘是否在线以及该工作树是否被锁定。prune 清的是仓库里的管理元数据，不负责恢复目录，也不会替代文件备份。

步骤4：用 porcelain 输出完成最终确认

返回“终端 → 仓库根目录 → 工作树检查”路径，再列一次结构化清单：

# 清理后重新读取完整清单，确认没有误删有效工作树
git worktree list --porcelain
# 需要简短人读列表时，再用普通格式复核路径
git worktree list

理想结果是主工作树和仍有效的 linked worktree 都保留，已删除目录对应的条目消失。若只是移动了工作树目录而目录本身仍在，先尝试在仓库根目录执行 git worktree repair ；不要用 prune 把可修复的工作树当成失联项。

常见问题

删除分支后一定要执行 prune 吗？

不一定。分支引用和工作树管理元数据是两条关系；目录仍存在时应按工作树生命周期处理，只有目录消失后留下失联元数据，才需要 prune。

prune -n 会删除文件吗？

不会。它用于预览 Git 准备清理的管理元数据；确认路径确实不存在后，再执行不带 -n 的命令。

为什么有效工作树没有被自动清理？

因为 Git 仍能看到目录，或者该工作树被 git worktree lock 锁定。先确认挂载盘和目录可访问性，再决定 remove、repair 或保留。

清理 worktree 的核心不是“看到旧分支就删除”，而是先核对目录生命周期：仍存在的工作树用 remove，已经消失的工作树用 prune，移动过但仍存在的工作树用 repair。