Docker容器内git checkout报错分支已在worktree检出如何解决

该报错由Git worktree内部元数据错乱触发：你的环境中多个分支的worktree注册记录都指向了同一个物理路径/<path>/workspaces/worktrees/branch4，Git的安全校验规则会禁止同一路径绑定多个不同分支的worktree，也禁止单个分支同时被检出到多个工作区，因此切换分支时直接抛出异常。
这类问题在Docker挂载Git仓库的场景下非常常见：容器重建时实例标识变化、卷挂载路径不一致、启动脚本错误地将所有分支的worktree绑定到同一路径，都会导致元数据不匹配。git worktree prune仅会自动清理物理路径已不存在的无效记录，对同路径绑定多分支的错乱场景完全无效；如果重克隆仓库时持久化卷中残留了旧的.git/worktrees元数据，或者容器启动逻辑未修正，哪怕重克隆也会复现问题。

1. 全量清理错误worktree元数据 #

不要在运行业务的容器内操作，直接在宿主机侧（或挂载了对应持久化卷的调试容器内）进入仓库根目录执行操作：

• 先备份本地未提交改动，避免数据丢失：

  git stash push -m "backup before worktree metadata fix"
  

• 直接清空Git存储的所有非主工作区注册记录：

  cd /<path>/workspaces/repo
  rm -rf .git/worktrees/*
  

• 执行校验，正常情况下输出仅保留主工作区记录：

  git worktree list
  

  预期输出：

  /<path>/workspaces/repo             9ab1cee0 [master]
  

2. 修正容器侧的Git配置逻辑 #

仅清理元数据不修正容器启动逻辑的话，重建容器后问题会100%复现，需要逐一排查修正以下配置：

• 禁止将所有分支的worktree创建到同一个固定路径，每个分支对应的worktree必须分配独立的、和分支名一一映射的物理路径，例如/<path>/workspaces/worktrees/branch1对应branch1、/<path>/workspaces/worktrees/branch2对应branch2，不能所有分支共用branch4目录。
• 如果使用的是用完即销的临时容器，不要将.git/worktrees目录持久化到宿主机卷，避免容器销毁后残留的元数据和新容器实例路径不匹配。
• 在容器启动脚本的Git操作逻辑前，增加git worktree prune --expire now命令，自动清理已销毁容器实例对应的无效worktree记录。

3. 权限异常兜底处理 #

如果完成上述步骤后切换分支仍报相同错误，检查仓库.git目录的权限：容器内运行Git的用户如果没有.git目录的完整读写权限，Git无法更新worktree注册记录，也会抛出虚假的"already checked out"报错。执行以下命令修正权限即可：

# 替换为容器内运行Git的实际用户和用户组
chown -R <git-run-user>:<git-run-user-group> /<path>/workspaces/repo

验证修复 #

启动新容器后，先执行git worktree list确认不存在重复路径的worktree记录，再执行git checkout <target-branch>即可正常切换分支。

内容的提问来源于stack exchange，提问作者Nathaniel N