修复 Git "无法删除被 Worktree 使用的分支" 错误

错误现象

你执行：

git branch -d feat/old-feature

Git 拒绝：

error: Cannot delete branch 'feat/old-feature' checked out at '/home/user/myapp-old-feature'

或变体：

fatal: Cannot delete branch 'feat/old-feature' which is checked out at '/home/user/myapp-old-feature'

**这不是 Bug。Git 是在保护你。**下面告诉你究竟发生了什么，以及 60 秒内如何修复。

为什么 Git 阻止删除

每个 Git 分支都有 HEAD —— 它指向的具体 commit。当一个 worktree 检出了这个分支，它的工作目录反映的就是这个 HEAD。如果 Git 让你删除分支：

该 worktree 将处在一个不存在的分支上
你在那里做的任何 commit 都会进入 detached HEAD（容易丢）
Git 内部引用（HEAD、ORIG_HEAD、reflog）会指向一个幽灵分支

所以 Git 阻止你，是出于安全。

错误信息甚至告诉了你哪个 worktree 在用这个分支：checked out at '/home/user/myapp-old-feature'。这就是你要处理的路径。

修复 1：先删 Worktree（推荐）

如果 worktree 和分支你都不要了（最常见情况）：

# 第 1 步 —— 删除 worktree
git worktree remove /home/user/myapp-old-feature

# 第 2 步 —— 现在删除分支
git branch -d feat/old-feature

两条命令搞定。

如果 worktree 有未提交改动，Git 会拒绝 worktree remove，见修复 3 或正确清理指南。

修复 2：把 Worktree 切到其他分支

如果你想保留 worktree 文件夹，但不再让它占着这个分支：

# 进入 worktree
cd /home/user/myapp-old-feature

# 切到别的分支
git checkout main  # 或任意其他分支

# 回去删除原分支
cd -
git branch -d feat/old-feature

这适用于你想复用这个 worktree 做别的任务但要甩掉老分支。

修复 3 ：强制删除（当你真的不在乎时）

如果你确定要删这个分支，哪怕还有 worktree 引用它，并且你已经接受了后果：

# 如果 worktree 文件夹已被手动删除或移动：
git worktree prune

# 删除分支
git branch -d feat/old-feature

# 如果 -d 还抱怨（分支未合并），用 -D：
git branch -D feat/old-feature

-D（大写）= 强制删除，即便未合并。

警告： -D 会丢弃该分支上无法从其他分支到达的 commit。如果你没有 git reflog 打底，这些 commit 基本就丢了。

变种：Worktree 文件夹已经不见了

常见场景：你用 rm -rf 删了 worktree 文件夹，但 Git 还以为它存在：

$ git branch -d feat/old-feature
error: Cannot delete branch 'feat/old-feature' checked out at '/home/user/myapp-old-feature'

$ ls /home/user/myapp-old-feature
ls: cannot access ...: No such file or directory

修复： git worktree prune 清理文件夹不存在的 worktree 引用：

git worktree prune
git branch -d feat/old-feature

如果 prune 没处理掉（旧版 Git，或 worktree 被锁定），手动检查：

git worktree list
# 找到死掉的条目，然后：
git worktree remove --force /已经不存在的/路径

变种："fatal: not a working tree"

在 git worktree remove 时看到：

fatal: '/home/user/myapp-old-feature' is not a working tree

意味着 Git 不认识这个路径。选项：

# 看 Git 认为存在什么：
git worktree list

# 如果你的目标路径在那里但大小写或末尾斜杠不同，
# 从 `list` 复制精确路径再试

# 如果文件夹真的不在了：
git worktree prune

变种：锁定的 Worktree

有些 worktree 被锁定了（有意或无意）。你会看到：

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

或：

error: ... is locked

先解锁：

git worktree unlock /home/user/myapp-old-feature
git worktree remove /home/user/myapp-old-feature
git branch -d feat/old-feature

一条命令：连锅端掉 Worktree + 分支

知道自己在做什么、想赶紧了事：

WT=/home/user/myapp-old-feature
BR=feat/old-feature
git worktree remove --force "$WT" && git branch -D "$BR"

或者做成 shell 函数（加到 .zshrc/.bashrc）：

wtkill() {
  local wt="$1"
  local branch="$2"
  git worktree remove --force "$wt" && git branch -D "$branch"
}
# 用法：
# wtkill /home/user/myapp-old-feature feat/old-feature

以后怎么避免这个错误

任务完成立刻清理 worktree —— 别留孤儿
每周跑一次 git worktree list —— 盘点还剩什么
永远别用 rm -rf 删 worktree 文件夹 —— 用 git worktree remove
用一个帮你追踪 worktree 的工具 —— ParallelCode 把所有 worktree 集中显示，一键删除

别再手动管理 worktree。 ParallelCode 把你所有仓库的每个 worktree 可视化呈现。删除、重命名、归档都是一键。

免费下载 ParallelCode →

为什么你用 ParallelCode / Claude Code 时也会遇到

如果你用 Claude Code、Cursor Agent 或 ParallelCode 的 worktree 流程，这个错误会在以下情况出现：

某个代理中途崩溃留下了 worktree
你在 ParallelCode UI 里删了任务但跳过了清理步骤
两个工具都为同一分支名创建了 worktree

修复方法一样 —— git worktree remove 加 git branch -d。ParallelCode 的 "删除任务" 按钮一键两事；手动用户需要两条命令。

总结：60 秒修复清单

# 99% 的情况：
git worktree remove <错误信息里的路径>
git branch -d <分支名>

# Worktree 文件夹没了？
git worktree prune
git branch -d <分支名>

# Worktree 被锁定？
git worktree unlock <路径>
git worktree remove <路径>
git branch -d <分支名>

# 放弃治疗，强制删除：
git worktree remove --force <路径>
git branch -D <分支名>