git worktree 是同一个仓库的另一份工作目录:独立文件、独立分支,共享历史和 remote。每个 Claude Code 会话占一个 worktree,一个会话的编辑就永远碰不到另一个会话的文件。
一句话结论
结论
官方每个并行会话用
claude --worktree <名字> 起在自己的 worktree 里:各有独立文件和分支,一边做 feature 一边修 bug 互不干扰;worktree 分支是普通 git 分支,改完照常 merge 或发 PR 收回来,退出会话时 Claude 会引导你清理。
做法步骤
- 确认问题确实是「互踩」。症状:同一个目录里开了两个 session,A 会话的
git status冒出 B 会话的改动、测试跑一半文件被改。官方worktree 的定位就是「running each Claude Code session in its own worktree means edits in one session never touch files in another」。前提:必须是 git 仓库。 - 开第一个隔离会话。在仓库里运行
claude --worktree feature-auth(简写-w)。官方默认在仓库根的.claude/worktrees/feature-auth/创建 worktree,新分支名为worktree-feature-auth,从仓库默认分支(通常 main)拉出。省略名字会自动生成一个。首次使用前需在该目录跑过一次claude接受 workspace trust。 - 换个名字再开第二个。另一个终端运行
claude --worktree fix-login-bug,两个会话从此各改各的。官方建议把.claude/worktrees/加进.gitignore,避免 worktree 内容出现在主 checkout 的未跟踪文件里。 - 初始化环境。worktree 是全新 checkout,依赖要重装,
.env这类 gitignored 文件也不在。官方在项目根加一个.worktreeinclude文件(.gitignore 语法),列出.env、.env.local等,之后每个新 worktree 自动带上;只有「匹配模式且本身被 gitignore」的文件才会被复制。 - 收回改动。官方worktree 与主 checkout 共享
.git目录和 remote,在里面git commit、push 都照常工作。本站观点所以合并没有任何特殊仪式:push 后发 PR,或回主 checkoutgit merge worktree-feature-auth,当普通分支处理即可。 - 清理。官方退出交互会话时 Claude 检查 worktree:干净且未命名的自动删掉;里面还有改动或新 commit 的,会问你 keep 还是 remove。
claude -p非交互跑出来的 worktree 没有退出提示,手动git worktree remove <路径>(有未提交改动加--force),git worktree list随时查看现存的。 - 两个进阶开关。官方① 会话中途直接说「work in a worktree」,Claude 会用 EnterWorktree 工具当场建一个;② subagent 也能各占一个 worktree:自定义 subagent 的 frontmatter 加
isolation: worktree(subagent 基础见 D10 · Subagents)。若希望 worktree 从当前未推送的工作(而非默认分支)拉出,settings 里设"worktree": {"baseRef": "head"}。
可直接抄的 prompt
在一个新的 worktree 里做这个任务:<任务描述>。
要求:
1. 用 worktree 隔离,不要动我主 checkout 里的任何文件;
2. 进入 worktree 后先初始化环境:安装依赖,检查 .env 等本地配置文件
是否存在,缺了先列出来问我;
3. 改完运行 <测试命令>,通过后 commit 到 worktree 分支,
最后告诉我分支名和改动摘要,由我决定 merge 还是发 PR,你不要自己合并。来源与最后核实日期
- 官方Run parallel sessions with worktrees,抓取于 2026-08-05。
- 最后核实:2026-08-05 · volatility:high(清理、baseRef、EnterWorktree 审批等行为近几个版本变动频繁)。