Worktrees 并行工作区

Git worktree 是同一个仓库历史和远端下的另一个工作目录。Claude Code 用它来隔离并行会话:一个终端做新功能,另一个终端修 bug,文件改动不会直接撞在同一个 checkout 里。

#何时使用

大型 Monorepo 可以用 worktree.sparsePaths 和 symlinkDirectories 减少每个工作区的检出范围,配置示例见 大型代码库与 Monorepo。

Claude Code 桌面端的新并行 session 会自动创建 worktree。本文主要讲 CLI。

#启动 worktree 会话

传 --worktree 或 -w 即可创建隔离工作区并在里面启动 Claude。

claude --worktree feature-auth

默认位置和分支名:

再开一个终端可以启动第二个隔离会话:

claude --worktree bugfix-123

省略名称时,Claude Code 会生成一个随机名称:

claude --worktree

会话中也可以直接要求 Claude “work in a worktree”。Claude 会通过 EnterWorktree 工具创建并进入 worktree。已经进入后,它还可以切换到 .claude/worktrees/ 下的另一个 worktree,原 worktree 会留在磁盘上。

建议把 Claude 自动创建的目录加入 .gitignore:

.claude/worktrees/

#Base branch

默认情况下,新 worktree 从仓库默认分支 origin/HEAD 创建,相当于基于远端干净状态开一条新分支。如果没有远端或 fetch 失败,会回退到当前本地 HEAD。

如果你希望 worktree 继承当前分支的未推送提交和开发状态,在 settings 里设置:

{
  "worktree": {
    "baseRef": "head"
  }
}

baseRef 只接受两个值:

要基于 GitHub PR 创建 worktree,传 PR 号并加 #,或传完整 PR URL:

claude --worktree "#1234"

Claude Code 会从 origin fetch pull/<number>/head,并在 .claude/worktrees/pr-<number> 创建工作区。

#复制本地配置

Worktree 是一个新 checkout,主目录里的未跟踪文件不会自动出现。常见例子是 .env、.env.local、本地 secrets 文件。

在仓库根目录添加 .worktreeinclude,可让 Claude 创建 worktree 时复制指定 gitignored 文件。语法沿用 .gitignore 风格。

.env
.env.local
config/secrets.json

重要边界:

#子代理 worktree 隔离

子代理也可以在临时 worktree 里运行,这样多个 agent 并行修改文件时不会互相覆盖。

---
name: fixer
description: 修复独立问题。需要改文件时使用隔离 worktree。
tools: Read, Grep, Glob, Edit, Bash
isolation: worktree
---

你在隔离 worktree 中工作。保持改动聚焦,完成后说明变更文件和验证结果。

也可以直接要求 Claude “use worktrees for your agents”。子代理 worktree 使用和 --worktree 相同的 base branch 策略:默认从远端默认分支开始,除非 worktree.baseRef 设为 head。

如果子代理结束时没有改动,临时 worktree 会自动移除。产生改动时,Claude 会保留必要信息供你处理。

#清理策略

退出 --worktree 会话时,Claude Code 会根据改动状态决定是否清理:

子代理和后台 session 创建的 worktree 会被周期清扫。只有满足这些条件才会删除:

• 超过 cleanupPeriodDays
• 没有未提交改动
• 没有未跟踪文件
• 没有未推送提交

你用 --worktree 显式创建的 worktree 不会被这个后台清扫自动删除。

运行中的 agent worktree 会被 git worktree lock 锁住,防止并发清理误删。agent 完成后锁会释放。

#手动管理

需要完全控制位置、分支或已有分支时,直接使用 Git 命令。

git worktree add ../project-feature-a -b feature-a

git worktree add ../project-bugfix bugfix-123

进入手动 worktree 后启动 Claude:

cd ../project-feature-a
claude

常用维护命令:

每个 worktree 都是独立工作目录。依赖安装、虚拟环境、生成文件、数据库迁移等项目初始化步骤,需要按项目实际情况重新处理。

#非 Git 版本控制

Claude Code 默认用 Git worktree。SVN、Perforce、Mercurial 或其他版本控制系统,可以通过 WorktreeCreate 和 WorktreeRemove hooks 自定义创建和清理逻辑。

{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
          }
        ]
      }
    ]
  }
}

这个 hook 从 stdin 读取 worktree 名称,创建工作目录,并把目录路径打印给 Claude Code。使用自定义 WorktreeCreate 时,默认 Git 创建逻辑会被替换,.worktreeinclude 也不会自动处理;需要在 hook 脚本里自己复制本地配置。

#常见误区

#官方参考

• Run parallel sessions with worktrees
• Create custom subagents
• Claude Code settings
• Hooks reference
• Git worktree documentation