如何删除 git worktree（以及常见报错的解决办法）

正常流程

git worktree list                 # 找到路径
git worktree remove ../app-search # 删除 worktree 目录
git branch -d feat/search         # 分支已合并的话，删掉分支

删除 worktree 不会删除它的分支和 commit，它们会留在仓库里，直到你自己删掉分支。

常见报错怎么解决

error: cannot delete branch 'feat' used by worktree at '…'

你对一个仍被 worktree 检出的分支执行了 git branch -d 或 -D。先删 worktree，再删分支：

git worktree remove ../app-search
git branch -d feat/search

如果 worktree 的目录已经不在了，git 仍认为分支在那里被检出。git worktree list -v 会把它标成 prunable。执行 git worktree prune 后，就能删掉这个分支了。

fatal: '…' contains modified or untracked files, use --force to delete it

这个 worktree 里有会丢失的改动。强制删除之前先看一眼：

git -C ../app-search status --short

把要留的提交或 stash 掉，再正常删除。git worktree remove --force 会永久删掉这些文件，它们从没提交过，reflog 也救不回来。

fatal: cannot remove a locked working tree, lock reason: …

有人锁定了这个 worktree，通常是还在用它的工具或 AI agent。比如 Claude Code 会在会话运行期间锁定它创建的 worktree。确认没有程序在里面工作后：

git worktree unlock ../app-search
git worktree remove ../app-search

git 也会提示用 remove -f -f 一步删除被锁定的 worktree。只在清楚里面有什么时才这样做。

fatal: '.' is a main working tree

主 worktree 就是你最初 clone 的目录，不能用 git worktree remove 删除。要删整个仓库，直接删目录。

fatal: 'feat' is already used by worktree at '…'

这不是删除时的报错，但清理时经常一起遇到：你想检出的分支已经被另一个 worktree 占用了。要么去那个 worktree 里工作，要么先把它删掉。

如果你用 rm -rf 或访达删了目录

git worktree prune --dry-run -v   # 先看会清理什么
git worktree prune -v

直接删目录，git 并不知道。.git/worktrees/ 里的记录还在，分支也仍被视为已检出。prune 会清掉那些目录已经不存在的 worktree 记录，不会动真实存在的 worktree、分支或 commit。

一次删除很多 worktree

写个循环遍历 git worktree list --porcelain，可以把主目录以外的 worktree 全删掉，但别闭着眼这么做。每个 worktree 里都可能有未提交的工作、从没 push 过的 commit，或者 PR 被 squash 合并的分支（git branch --merged 认不出来）。批量删除之前，先按清理清单里的 6 项检查过一遍。

Orchard 会为你 Mac 上的每个 worktree 做这些检查，并列出已经进了 main 的那些和理由，比如“PR #142 已于 3 天前合并”。清理前会先把未提交的文件和分支 HEAD 快照下来，7 天内都能恢复。有 agent 在运行的 worktree 一律不动。

常见问题