Claude Code 如何用 --worktree 在隔离工作树中并行开发？claude-howto 的 baseRef 与 sparsePaths 配置

Claude Code 如何用 --worktree 在隔离工作树中并行开发？claude-howto 的 baseRef 与 sparsePaths 配置

【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto

当你需要在保留当前工作区的同时，让另一个 Claude Code 会话在独立分支上改代码时，反复git stash和切换分支会打断两边的上下文。claude --worktree（简写claude -w）可以让 Claude Code 直接在一个隔离的 git worktree 中启动，两个会话各自操作独立的分支副本。claude-howto 仓库在 09-advanced-features/README.md 的 Git Worktrees 章节和 10-cli/README.md 的 CLI 参考中记录了完整的启动方式与worktree配置项，本文按文档给出的操作步骤整理。

用 --worktree 启动隔离会话

在 git 仓库根目录执行：

# Start Claude Code in an isolated worktree claude --worktree # or claude -w

-w, --worktree标志的作用是启动在一个隔离的 git worktree 中（见 10-cli/README.md Core Flags 表）。从 v2.1.233 开始，该标志除了不带参数使用外，还可以接受一个 GitHub PR URL 或 GitLab merge-request URL，直接基于对应的评审分支工作。

worktree 会在仓库内的固定位置创建：

<repo>/.claude/worktrees/<name>

启动后可以确认<repo>/.claude/worktrees/目录下出现了新的 worktree，并且新会话的文件改动不会出现在主工作区——这就是文档描述的"parallel work on different branches without stashing or switching"。

配置 baseRef：新分支从哪里切出

worktree.baseRef自 v2.1.133 加入，控制claude --worktree的分支基点是origin/<default>还是本地HEAD，两个取值（见 09-advanced-features/README.md）：

• "fresh"（默认）——从origin/<default-branch>切出，忽略本地未推送的提交。这是行为变更：它回退了 v2.1.128 引入的行为，因此在 v2.1.128 之后依赖本地HEAD切出分支的用户必须显式重新设置；
• "head"——从本地HEAD切出，保留未推送的提交。

在~/.claude/settings.json中设置：

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

选择依据：如果你的并行任务必须包含本地尚未推送的提交（例如上一个会话刚改完但还没 push），用"head"；如果只需要基于远端默认分支的最新状态开一个干净分支，保留默认的"fresh"即可。CHANGELOG.md 中 v2.1.138 的同步记录也确认了这一默认值的行为回退。

配置 sparsePaths：monorepo 中只检出需要的包

在 monorepo 里，整仓库检出会让每个 worktree 占用大量磁盘和克隆时间。worktree.sparsePaths让 worktree 执行 sparse-checkout，只检出列出的路径：

{ "worktree": { "sparsePaths": ["packages/my-package", "shared/"] } }

上面的路径是文档中的示例，替换成你 monorepo 中实际要操作的包目录即可。文档给出的适用场景是"sparse-checkout specific packages in monorepos for faster startup"。

可选：控制后台会话是否也进 worktree

如果你用后台会话（/bg、claude --bg或 Agent View），worktree.bgIsolation（v2.1.143 加入）控制它们是否也获得自己的 worktree：

• 默认：后台会话在<repo>/.claude/worktrees/下创建隔离 worktree，与--worktree相同；
• "none"：后台会话直接编辑当前工作副本。适用于 worktree 不实际（例如大量原生构建产物）或后台 agent 必须与前台会话协同编辑的场景。

{ "worktree": { "bgIsolation": "none" } }

文档明确指出了这个取舍："none"去掉了 worktree 隔离的安全网，前台和后台会话的并发修改可能直接在活动工作副本中产生合并冲突。

进入、退出与清理 worktree

• EnterWorktree/ExitWorktree是内置工具，分别用于进入和退出（并清理）当前 worktree。自 v2.1.157 起，EnterWorktree支持在会话中途在多个 Claude 管理的 worktree 之间切换；
• WorktreeCreate/WorktreeRemove是 worktree 创建和移除时触发的 hook 事件，可以挂接自己的通知脚本。

清理规则由文档直接说明：

• 如果 worktree 中没有任何修改，会话结束时会自动清理；
• 自 v2.1.157 起，Claude 管理的 worktree 在 agent 完成后保持解锁状态，因此可以用git worktree remove/git worktree prune手动清理残留的 worktree。执行这两条命令前请先确认没有会话还依赖该 worktree，它们会实际删除 worktree 目录。

另外，01-slash-commands/README.md 中还提供了/batch <instruction>命令，用 worktrees 编排大规模并行修改；/worktree斜杠命令可以在会话内创建隔离工作区（见 QUICK_REFERENCE.md）。

文档列出的适用场景

09-advanced-features/README.md 给出的 use cases：在主分支保持不动的同时开发特性分支、在隔离环境中跑测试而不影响工作目录、在一次性环境里试验实验性修改、在 monorepo 中 sparse-checkout 指定包以加快启动。这些场景中任何一个都可以直接对应本文的启动与配置步骤。

需要注意的边界：worktree.baseRef与worktree.bgIsolation分别要求 v2.1.133 和 v2.1.143 及以后的 Claude Code；--worktree接受评审 URL 的能力要求 v2.1.233 及以后。版本低于对应要求时，相应配置不会生效。

【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto