本页目录8
- `claude --worktree <name>` 在独立分支和目录中启动 Claude，多终端并行编辑互不干扰
- `.worktreeinclude` 文件声明哪些被 gitignore 的本地配置（如 `.env`）需自动复制进每个新 worktree
- 子代理可通过 `isolation: worktree` frontmatter 或口头指令在独立 worktree 中并行运行，消除文件冲突
- 会话退出时无变更自动清理（命名会话则改为提示保留），有变更则提示保留；非交互式 `-p` 模式需手动 `git worktree remove`
- 可通过 `WorktreeCreate` / `WorktreeRemove` hooks 支持 SVN、Perforce 等非 git 版本控制系统
本文是对官方文档《Run parallel sessions with worktrees》的中文要点摘要，完整内容以原文为准。原文链接：https://code.claude.com/docs/en/worktrees
什么是 Worktree 及为何使用
git worktree 允许同一个仓库拥有多个独立的工作目录，各目录拥有独立文件和分支，但共享同一份历史与远端。在 Claude Code 中，每个会话运行在独立 worktree 里，不同终端的编辑互不干扰——可以在一个终端开发新功能，同时在另一个终端修复 Bug，两者完全隔离。
桌面版 Claude Code 为每个新会话自动创建 worktree；本文重点介绍 CLI 的手动用法。
启动 Worktree 会话
使用 --worktree（简写 -w）标志启动 Claude，自动创建隔离 worktree：
claude --worktree feature-auth
默认情况下，worktree 创建于仓库根目录的 .claude/worktrees/<name>/，同时新建名为 worktree-<name> 的分支。省略名称时 Claude 自动生成（如 bright-running-fox）。在会话进行中也可以直接告诉 Claude「在 worktree 中工作」，Claude 会调用 EnterWorktree 工具创建一个新的 worktree；进入某个 worktree 后，可通过 EnterWorktree 传入目标路径，直接切换到 .claude/worktrees/ 下的其他 worktree，原 worktree 在磁盘上保持不变。
建议：将 .claude/worktrees/ 加入 .gitignore，避免 worktree 内容出现在主检出的未跟踪文件列表中。
首次在某目录使用 --worktree 前，需先运行一次 claude 接受工作区信任对话框；非交互式 -p 模式跳过信任检查，可直接使用 claude -p --worktree。
指定基础分支
默认从 origin/HEAD（远端默认分支）创建 worktree，起点干净；若未配置远端或拉取失败，则回退到当前本地 HEAD。若需始终从本地 HEAD（含未推送提交）分支，可在 settings 中配置：
{
"worktree": {
"baseRef": "head"
}
}
baseRef 只接受 "fresh"（默认）或 "head" 两个值，不支持任意 git ref。也可传入 PR 编号（前缀 #）或完整 GitHub PR URL 直接检出对应拉取请求，worktree 创建于 .claude/worktrees/pr-<number>：
claude --worktree "#1234"
复制被 gitignore 的文件
Worktree 是全新检出，.env、.env.local 等未跟踪的本地文件默认不存在。在项目根目录创建 .worktreeinclude 文件（语法同 .gitignore），即可在创建 worktree 时自动复制指定文件：
.env
.env.local
config/secrets.json
只有「匹配规则 且 已被 gitignore」的文件才会被复制，已跟踪文件不会重复。此机制同样适用于子代理 worktree 和桌面版并行会话。
子代理 Worktree 隔离
多个子代理并行运行时，可让每个代理拥有独立 worktree 来避免文件冲突：
- 临时：对话中告诉 Claude「为你的代理使用 worktree」
- 永久：在自定义子代理的 frontmatter 中添加
isolation: worktree
每个子代理获得一个临时 worktree，完成后若无变更则自动删除。子代理 worktree 使用与 --worktree 相同的基础分支配置。
清理机制
| 场景 | 行为 |
|---|---|
| 无未提交变更、无未跟踪文件、无新提交 | 自动删除 worktree 及其分支；但若会话已命名，则改为提示，便于保留以备后用 |
| 有未提交变更、未跟踪文件或新提交 | 提示保留或删除（删除会丢弃所有未提交变更、未跟踪文件及提交） |
非交互式（-p）模式 | 不自动清理，需手动运行 git worktree remove |
Claude 为子代理及后台会话创建的 worktree，在超过 cleanupPeriodDays 设置的天数、且无未提交变更、无未跟踪文件、无未推送提交时自动清理。代理运行期间 Claude 执行 git worktree lock 防止并发清理，完成后释放锁。强制删除含未提交变更或未跟踪文件的 worktree 时需加 --force。
注意：通过 --worktree 手动创建的 worktree 不受自动清理扫描影响，只有子代理及后台会话的 worktree 才会被自动扫描清理。
手动管理 Worktree
需要精确控制 worktree 位置或分支时，可直接用 git 命令操作：
# 新建分支并创建 worktree
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 worktree list
# 完成后删除
git worktree remove ../project-feature-a
注意：每个新 worktree 需独立初始化开发环境（安装依赖、配置虚拟环境等）。
非 git 版本控制系统
对于 SVN、Perforce、Mercurial 等，可配置 WorktreeCreate 和 WorktreeRemove hooks 完全替代默认的 git 逻辑。Hook 从 stdin 读取 worktree 名称，完成自定义检出后将目录路径打印到 stdout，Claude Code 将其作为会话工作目录。
使用 hooks 时 .worktreeinclude 不会自动处理，需在 hook 脚本内手动复制本地配置文件。官方提供了 SVN svn checkout 的完整示例，配合 WorktreeRemove hook 可实现完整的创建与清理闭环。详细输入 schema 见官方 hooks 参考文档。