Claude Code 深度学习手册

主题

Git Worktrees（并行工作树） ​

用 git worktree 给每个 Claude Code 会话开独立工作目录，让多个会话并行修改文件而互不干扰。

你的真实情况 ​

你已经在和 worktree 打交道：你的 auto memory 记着 kj-frontend-umi-bak（旧版归档），而且后台代理改文件前会自动建 .claude/worktrees/。worktree = 同一个仓库的多个工作副本，各在自己的分支，互不干扰。

去真实体验 ​

想干什么这样做
让某 subagent 在隔离副本里改它 frontmatter 设 isolation: worktree，或 Agent 调用时传 isolation: "worktree"
后台会话的隔离自动进 .claude/worktrees/；关掉用 worktree.bgIsolation: "none"
清理残留 worktreegit worktree list 看，git worktree remove <path> 删

对你的实际意义 ​

  • 你前端正在从 Umi 渐进改 Vue3——用 worktree 可以让一个会话在隔离副本里大改 Vue，主副本继续跑 Umi 不受影响。
  • 并行后台任务（前端 + SpringBlade 同时）天然各占一个 worktree，不会互相覆盖未提交改动。
  • 在 agent view 里删后台会话会连带删它的 worktree（含未提交改动）——先 commit/push。

官方文档要点 ​

以下为按官方文档整理的系统性参考。

是什么 ​

git worktree 是一个独立的工作目录，拥有自己的文件和分支，但与主检出（main checkout）共享同一个仓库历史和 remote。让每个 Claude Code 会话跑在自己的 worktree 里，一个会话里的编辑就永远不会动到另一个会话的文件——例如可以一个终端让 Claude 建新功能，另一个终端同时修 bug。worktree 是 Claude Code 多种并行方式之一：worktree 隔离的是「文件编辑」，而 subagents 和 agent teams 协调的是「工作本身」。本页讲的是 CLI 里的 worktree 隔离，全部前提是 git 仓库；非 git 系统见 Non-git version control。desktop app 会为每个新会话自动创建 worktree。

怎么工作 ​

  • 创建位置与分支命名：默认在仓库根目录的 .claude/worktrees/<value>/ 下创建 worktree，并新建一个名为 worktree-<value> 的新分支。
  • 基线分支（base branch）：worktree 从仓库默认分支 origin/HEAD 分叉，因此起点是一棵匹配 remote 的干净树。如果没有配置 remote 或 fetch 失败，则回退到当前本地 HEAD。可通过 settings 里的 worktree.baseRef 改为 "head"，让新 worktree 带上你未推送的提交和 feature 分支状态——这在隔离需要操作进行中工作的 subagent 时有用。baseRef 只接受 "fresh" 或 "head"，不接受任意 git ref。
  • 从 PR 分叉：传入以 # 前缀的 PR 号或完整 GitHub PR URL 时，Claude Code 会从 origin fetch pull/<number>/head，并在 .claude/worktrees/pr-<number> 创建 worktree。
  • 会话中创建：可以在会话里直接让 Claude「work in a worktree」，它会用 EnterWorktree 工具创建。
  • 拷贝 gitignored 文件：worktree 是全新检出，主仓库里的未跟踪文件（如 .env、.env.local）不会出现。在项目根放 .worktreeinclude 文件可在创建 worktree 时自动拷贝；该文件用 .gitignore 语法，只有「匹配某 pattern 且本身被 gitignore」的文件才会被拷，已跟踪文件永远不会被复制。
  • subagent 隔离：subagent 可跑在各自的 worktree 里避免并行编辑冲突。每个 subagent 拿到一个临时 worktree，当 subagent 无改动结束时自动移除。subagent worktree 使用与 --worktree 相同的 base branch。
  • 退出清理：退出 worktree 会话时清理行为取决于是否有改动（见 limits）。
  • 非 git 系统：worktree 隔离默认用 git。SVN/Perforce/Mercurial 等可配 WorktreeCreate 和 WorktreeRemove 钩子提供自定义创建与清理逻辑；因为钩子完全替换了默认 git 行为，此时用 --worktree 不会处理 .worktreeinclude，需在钩子脚本里自己拷贝本地配置文件。

怎么配置 / 用法 ​

启动会话进 worktree：claude --worktree feature-auth（或短写 -w）。省略名字会自动生成如 bright-running-fox：claude --worktree。第二个终端用不同名字 claude --worktree bugfix-123 开第二个隔离会话。

基线分支改为本地 HEAD（settings，见 /en/settings#worktree-settings）：

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

baseRef 只接受 "fresh" 或 "head"。

从 PR 分叉：claude --worktree "#1234"（也支持完整 GitHub PR URL），worktree 落在 .claude/worktrees/pr-<number>。

拷贝 gitignored 文件，项目根放 .worktreeinclude（.gitignore 语法）：

text
.env
.env.local
config/secrets.json

subagent 永久隔离：在 custom subagent 的 frontmatter 加 isolation: worktree；或会话里说「use worktrees for your agents」。

手动管理（Git 直接操作）：

  • 新建分支建 worktree：git worktree add ../project-feature-a -b feature-a
  • 从已有分支建：git worktree add ../project-bugfix bugfix-123
  • 进去启动：cd ../project-feature-a && claude
  • 列出：git worktree list
  • 移除：git worktree remove ../project-feature-a

非 git（WorktreeCreate 钩子，从 stdin 读 name，输出目录路径）：

json
{
  "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\"'"
          }
        ]
      }
    ]
  }
}

配套用 WorktreeRemove 钩子做会话结束清理。

建议：把 .claude/worktrees/ 加进 .gitignore，避免 worktree 内容在主检出里显示为未跟踪文件。

什么时候用 ​

  • 需要同时跑多个 Claude Code 会话且改动不能互相污染时（如一个终端建功能、另一个终端修 bug）——worktree 隔离文件编辑。
  • 想用 worktree 隔离 subagent 的并行编辑，避免冲突时——加 isolation: worktree 或让 Claude 用 worktree 跑 agents。
  • 需要基于某个 PR 单独检出工作时——用 --worktree "#1234"。
  • 当 subagent 需要操作进行中的（未推送）工作时——把 worktree.baseRef 设为 "head"。
  • 需要完全自定义 worktree 位置/分支，或检出某个已存在分支、把 worktree 放到仓库外时——用 git worktree 手动管理，或配 WorktreeCreate 钩子。
  • 用 SVN/Perforce/Mercurial 等非 git VCS 时——配 WorktreeCreate/WorktreeRemove 钩子，而不是依赖默认 git 行为。
  • 区分用途：worktree 管文件隔离；要把工作派发到隔离检出里、或在会话间切换，应配合 subagents / agent teams / sessions 使用。

限制 / 坑 ​

  • 首次在某目录用 --worktree 前，必须先在该目录跑一次 claude 接受 workspace trust 对话框；未接受信任时 --worktree 会报错退出并提示先跑 claude——即使和 -p 组合也是如此。
  • worktree 是全新检出，主仓库的未跟踪文件（.env、.env.local 等）默认不存在，需要靠 .worktreeinclude 拷贝。
  • 配了 WorktreeCreate 钩子（非 git 场景）后，--worktree 不再处理 .worktreeinclude，本地配置文件得在钩子脚本里自己拷。
  • 退出清理分情况：无未提交改动、无未跟踪文件、无新提交时——worktree 和分支自动移除（但若会话已命名，则改为提示你以便保留）；有未提交改动/未跟踪文件/新提交时——提示你保留或移除，移除会删掉目录和分支并丢弃所有未提交改动、未跟踪文件和提交。
  • 非交互运行：--worktree 与 -p 一起创建的 worktree 不会自动清理（因为没有退出提示），需用 git worktree remove 手动删。
  • 因崩溃或中断而残留（orphaned）的 subagent worktree，只有在超过 cleanupPeriodDays 设置、且无未提交改动、无未跟踪文件、无未推送提交时，才会在启动时被清扫；用 --worktree 创建的 worktree 永远不会被这个清扫流程移除。
  • worktree.baseRef 只接受 "fresh" 或 "head"，不能填任意 git ref。
  • 手动建 worktree 后要记得在每个新 worktree 里初始化开发环境：装依赖、建虚拟环境、跑项目所需的 setup。

硬事实速查（20 条） ​

  • flag：--worktree，短写 -w。
  • 默认 worktree 路径：.claude/worktrees/<value>/（仓库根目录下）。
  • 默认新分支名：worktree-<value>。
  • 省略名字时自动生成形如 bright-running-fox 的名字。
  • 示例命令：claude --worktree feature-auth / claude --worktree bugfix-123 / claude --worktree。
  • 会话中创建 worktree 用的工具：EnterWorktree（见 /en/tools-reference）。
  • base branch 默认：从仓库默认分支 origin/HEAD 分叉；无 remote 或 fetch 失败时回退到本地 HEAD。
  • settings 字段：worktree.baseRef，取值仅 "fresh" 或 "head"；"head" 让 worktree 带上未推送提交和 feature 分支状态。
  • PR 分叉：claude --worktree "#1234"（或完整 GitHub PR URL）；fetch origin 的 pull/<number>/head；worktree 落在 .claude/worktrees/pr-<number>。
  • 拷贝文件配置：项目根的 .worktreeinclude，用 .gitignore 语法；只拷「匹配 pattern 且被 gitignore」的文件。
  • subagent 永久隔离 frontmatter 字段：isolation: worktree。
  • subagent 临时 worktree 在无改动结束时自动移除。
  • 残留 subagent worktree 清扫依赖 cleanupPeriodDays 设置；--worktree 创建的 worktree 不受此清扫影响。
  • 信任前置：首次用 --worktree 前需先在该目录跑 claude 接受 workspace trust；未信任则 --worktree 报错退出（含与 -p 组合时）。
  • 手动管理命令：git worktree add ../project-feature-a -b feature-a；git worktree add ../project-bugfix bugfix-123；git worktree list；git worktree remove ../project-feature-a。
  • 非 git VCS 钩子：WorktreeCreate、WorktreeRemove（见 /en/hooks#worktreecreate）；钩子从 stdin 读 .name 字段（jq -r .name），需输出目录路径作为会话工作目录。
  • 非交互（-p）下 --worktree 创建的 worktree 不自动清理，需 git worktree remove。
  • 建议把 .claude/worktrees/ 加入 .gitignore。
  • desktop app 为每个新会话自动创建 worktree（/en/desktop#work-in-parallel-with-sessions）。
  • .worktreeinclude 适用于 --worktree、subagent worktree、desktop app 的并行会话。

官方出处：https://code.claude.com/docs/en/worktrees