它到底是什么

--worktree（简写 -w）在启动 Claude Code 时创建一个隔离的 git worktree，并在其中开始会话。worktree 是独立的工作目录，有自己的文件和分支，与主 checkout 共享同一份仓库历史和 remote。因此一个会话里的编辑不会碰到另一个会话的文件。

worktree 需要 git 仓库。SVN、Perforce、Mercurial 等其他版本控制系统需要配置 WorktreeCreate / WorktreeRemove Hook 来替代 git 逻辑。

用法

# 指定名字
claude --worktree feature-auth

# 简写
claude -w feature-auth

# 省略名字,自动生成
claude -w

# 基于某个 PR / MR 创建(需要给 # 加引号,避免 shell 把它当注释)
claude --worktree "#1234"

对 PR 的处理：

• --worktree 接受 #<number>、GitHub PR URL 和 GitLab MR URL。
• Claude Code 只从 URL 中读取编号。
• 它总是从仓库的 origin remote 拉取该变更的 head commit，并创建 .claude/worktrees/pr-<number>。
• 按 origin 的 host 选择拉取路径：github.com 用 pull/<number>/head,gitlab.com 用 merge-requests/<number>/head，其他 host 先试前者再试后者。
• 官方文档称，v2.1.233 之前只接受 #<number> 和 GitHub 风格的 PR URL。

在会话中也可以直接让 Claude "work in a worktree"，它会调用 EnterWorktree 工具创建。

与其他 flag 的组合 / 互斥

官方 worktrees 文档中明确提到的组合：

所抓取的官方文档中没有说明 --worktree 与其他 flag 的互斥关系，这里不做推断。

在 settings.json / env 的等价配置

所抓取的文档中没有与 --worktree 对应的环境变量，也没有能等价替代该 flag 的 settings 字段。下表是文档中与 worktree 行为相关的配置项：

• worktree.baseRef 不接受分支名。要从某个已有分支创建，请直接用 git worktree add。
• 官方文档提示：.worktreeinclude 只复制"匹配模式且被 gitignore"的文件，已跟踪文件不会被重复复制。

运行约束 / 限制

经典使用场景

• 并行开发：官方文档描述的用法是，在另一个终端用不同名字再运行一次命令，得到第二个隔离会话，一个做功能、另一个修 bug。
• 基于 PR / MR 的隔离环境：claude --worktree "#1234"。
• 隔离子 agent：让 Claude "use worktrees for your agents"，或在自定义 subagent 的 frontmatter 里加 isolation: worktree。子 agent 完成且无改动时，其临时 worktree 会自动删除。
• 非 git 仓库：用 WorktreeCreate Hook 从 stdin 的 JSON 读取 name，自行创建目录并输出路径。官方文档以 SVN checkout 为例。

常见坑

• -p 模式不清理：claude -p --worktree 创建的 worktree 退出时不会被清理。Claude Code 创建时加的锁会一直保留，直到之后某次会话的过期锁清扫将其释放。手动清理用 git worktree remove；若因锁被拒绝，先 git worktree unlock。
• 退出时的清理规则：交互会话退出时，如果 worktree 干净，未命名会话会被自动删除（含分支），命名会话会先询问你；如果有改动或新 commit，会询问保留还是删除。选择删除会连同分支和其中所有工作一起删掉。
• 复用名字会打开已有 worktree：目录已存在时，--worktree <name> 打开的是现有 worktree，而不是新建。在默认 "fresh" 基线下，如果该 worktree 无未提交改动、仍在 Claude Code 创建的分支上、且没有自己的 commit（或其 PR/MR 已合并且 remote 分支已删除），重新打开时会被重置到仓库默认分支；其他情况保持在原来的 tip。官方文档称 v2.1.208 之前总是回到旧 tip。
• "fresh" 基线不含本地未推送的工作：想让 worktree 带上当前的本地 commit，需设置 worktree.baseRef: "head"。
• .gitignore：官方建议把 .claude/worktrees/ 加入 .gitignore，否则 worktree 内容会在主 checkout 中显示为未跟踪文件。
• 新 worktree 没有依赖和 .env:worktree 是全新 checkout，需要自行安装依赖，或用 .worktreeinclude 复制被 gitignore 的文件。
• 使用 WorktreeCreate Hook 时 .worktreeinclude 不生效：需要在 Hook 脚本里自己复制文件。
• Git LFS 变成指针文件：用 git lfs install --local 配置 LFS 时，Claude Code 创建的 worktree 里是 LFS 指针文件而不是真实文件，需要在 worktree 内运行 git lfs pull。普通的 git lfs install（写入全局配置）不受影响。官方文档称 v2.1.247 之前会在创建时运行这些 driver。
• Hook 中的 ${CLAUDE_PROJECT_DIR} 不跟随 worktree：它仍指向会话启动时的项目根目录。需要 worktree 路径时，读取 Hook 输入 JSON 中的 cwd 字段。
• "Yes, and don't ask again" 的作用范围：在 worktree 会话中对 Bash 命令选择它，规则会保存到主 checkout 的 .claude/settings.local.json，对主 checkout 和该仓库的其他 worktree 都生效，并且不随 worktree 删除而消失。Windows 及文档所述的其他情况除外。官方文档称 v2.1.211 之前是保存在 worktree 内部。
• 从 worktree 内部启动再恢复会话可能被拒绝：出现 launch from the parent checkout 之类的提示时，应从主 checkout 启动。

来源

• Run parallel sessions with worktrees - Claude Code Docs
• CLI reference - Claude Code Docs（docs.claude.com/en/docs/claude-code/cli-reference 会 301 重定向到此地址。所抓取内容被截断，其中未能看到 --worktree / -w 的表格条目，该 flag 的行为以 worktrees 页面为准）
• Settings reference - Claude Code Docs（仅用于确认 cleanupPeriodDays 存在。所抓取内容中未见 worktree 设置小节，worktree.baseRef 的说明来自 worktrees 页面）