Git worktree 怎么清理失效工作区记录

Git worktree 用一份仓库对象让多个目录同时检出不同分支。临时工作树被删除、移动或磁盘恢复后，Git 可能仍保留对应的管理记录，于是列表里会出现已经不存在的路径。清理这类失效记录的稳妥顺序是：先列出状态，再用 dry-run 预览，确认后执行 prune，最后重新核对。不要直接删除 .git/worktrees 下的文件。

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

步骤一：列出 worktree 记录，先确认仓库范围

进入主工作树的仓库根目录，执行下面的命令。--porcelain 会把每个工作树拆成固定字段，适合逐项对照路径和分支。

# 查看本仓库的全部 worktree 记录，避免在错误仓库里清理
git worktree list --porcelain

重点看 worktree、HEAD 和 branch 三行。路径仍存在、分支仍在使用的条目先保留；只有目录确实不存在，或已确认不再需要的记录，才进入下一步。

步骤二：用 dry-run 预览哪些记录会被清理

确认仓库范围后，不要直接运行清理命令。先预览 Git 判断为过期的管理记录：

# 只打印候选项，不修改 worktree 元数据
git worktree prune --dry-run --verbose

--dry-run 是预览开关，--verbose 让清理候选更容易定位。输出中的路径或管理记录要和上一步对照；如果某个目录只是被移动，下一步不应 prune，而应保留它并准备 repair。

步骤三：确认候选后执行 prune

dry-run 输出符合预期后，再提交清理：

# 清理已确认失效的记录，并输出实际处理项
git worktree prune --verbose

# 仅在确实需要调整过期边界时使用；时间参数要按团队保留策略填写
git worktree prune --expire=now --verbose

默认策略更适合先保留一段时间的残留记录；--expire=now 会立即把符合条件的记录视为过期，适合已经核实目录不可恢复的情况。清理命令只处理 Git 的管理元数据，不会替你删除磁盘上的工作树文件。

步骤四：重新核对，移动目录则使用 repair

清理结束后再次列出记录，确保仍在使用的工作树没有被误处理：

# 复查清理后的 worktree 列表
git worktree list --porcelain

# 工作树只是换了位置时，重新关联它，而不是删除记录
git worktree repair /path/to/moved-worktree

这里的路径应替换为已经移动后的实际目录。若列表恢复了正确的 worktree 路径，说明应该保留的记录已修复；失效记录则不再出现。

参数与异常处理清单

常见问题

prune 会删除工作树目录吗？

不会。它清理的是 Git 管理的失效记录；磁盘目录本身需要由你按实际文件情况处理。

为什么不建议手工删除 .git/worktrees 文件？

手工操作容易漏掉锁、HEAD 或关联信息。用 prune、repair 让 Git 按自身格式维护记录更安全。

清理前一定要使用 --expire=now 吗？

不需要。先用默认规则预览即可；只有确定残留记录应立即过期时，才显式指定这个边界。