{/* TRANSLATED — 已翻译为中文 */}

> ## 文档索引
> 获取完整文档索引：https://code.claude.com/docs/llms.txt
> 使用此文件发现所有可用页面，然后再进一步探索。

# 使用工作树运行并行会话

> 在单独的 git 工作树中隔离并行 Claude Code 会话，避免更改冲突。涵盖 `--worktree` 标志、子代理隔离、`.worktreeinclude`、清理和非 git VCS 钩子。

[git 工作树](https://git-scm.com/docs/git-worktree)是一个独立的工作目录，拥有自己的文件和分支，与您的主检出共享相同的仓库历史和远程。在各自的工作树中运行每个 Claude Code 会话意味着一个会话中的编辑永远不会触及另一个会话中的文件，因此您可以让 Claude 在一个终端中构建功能，同时在另一个终端中修复 bug。

本页涵盖 CLI 中的工作树隔离。以下内容均假设为 git 仓库。对于其他版本控制系统，请参阅[非 git 版本控制](#非-git-版本控制)。[桌面应用](/en/desktop#work-in-parallel-with-sessions)会为每个新会话自动创建工作树。

工作树是并行运行 Claude 的几种方式之一。它们隔离文件编辑，而[子代理](/en/sub-agents)和[代理团队](/en/agent-teams)协调工作本身。请参阅[并行运行代理](/en/agents)比较各种方法，或直接跳转到[使用工作树隔离子代理](#使用工作树隔离子代理)以将工作树和子代理结合使用。

## 在工作树中启动 Claude

传递 `--worktree` 或 `-w` 以创建隔离的工作树并在其中启动 Claude。默认情况下，工作树在仓库根目录下的 `.claude/worktrees/<value>/` 创建，位于名为 `worktree-<value>` 的新分支上：

```bash theme={null}
claude --worktree feature-auth
```

要将工作树放在其他位置，请配置 [`WorktreeCreate` 钩子](#非-git-版本控制)。在另一个终端中使用不同的名称再次运行该命令以启动第二个隔离会话：

```bash theme={null}
claude --worktree bugfix-123
```

如果省略名称，Claude 会生成一个名称，例如 `bright-running-fox`：

```bash theme={null}
claude --worktree
```

您也可以在会话期间要求 Claude"在工作树中工作"，它会使用 [`EnterWorktree`](/en/tools-reference) 工具创建一个。

首次在目录中使用 `--worktree` 之前，请在该目录中运行 `claude` 一次以接受工作区信任对话框。如果尚未接受信任，`--worktree` 会退出并提示您先在该目录中运行 `claude`，包括与 `-p` 组合使用时。

<Tip>
  将 `.claude/worktrees/` 添加到您的 `.gitignore` 中，这样工作树内容不会作为未跟踪文件出现在主检出中。
</Tip>

### 选择基础分支

工作树从仓库的默认分支 `origin/HEAD` 创建分支，因此它们从与远程匹配的干净树开始。如果未配置远程或获取失败，工作树会回退到您当前的本地 `HEAD`。要始终从本地 `HEAD` 创建分支，请在[设置](/en/settings#worktree-settings)中将 `worktree.baseRef` 设置为 `"head"`。将 `baseRef` 设置为 `"head"` 使新工作树携带您未推送的提交和功能分支状态，这在隔离需要处理进行中工作的子代理时很有用。该设置仅接受 `"fresh"` 或 `"head"`，不接受任意 git 引用：

```json theme={null}
{
  "worktree": {
    "baseRef": "head"
  }
}
```

要从特定拉取请求创建分支，请传递以 `#` 为前缀的 PR 编号，或完整的 GitHub 拉取请求 URL。Claude Code 从 `origin` 获取 `pull/<number>/head` 并在 `.claude/worktrees/pr-<number>` 创建工作树：

```bash theme={null}
claude --worktree "#1234"
```

要完全控制工作树的创建方式，请配置 [`WorktreeCreate` 钩子](/en/hooks#worktreecreate)，它会完全替换默认的 `git worktree` 逻辑。

## 将 gitignore 文件复制到工作树

工作树是全新的检出，因此您主仓库中的未跟踪文件（如 `.env` 或 `.env.local`）不存在。要在 Claude 创建工作树时自动复制它们，请在项目根目录添加 `.worktreeinclude` 文件。

该文件使用 `.gitignore` 语法。只有匹配模式且被 gitignore 的文件才会被复制，因此已跟踪的文件永远不会被重复。

此 `.worktreeinclude` 将两个环境文件和一个密钥配置复制到每个新工作树中：

```text .worktreeinclude theme={null}
.env
.env.local
config/secrets.json
```

这适用于使用 `--worktree` 创建的工作树、[子代理工作树](#使用工作树隔离子代理)和[桌面应用](/en/desktop#work-in-parallel-with-sessions)中的并行会话。

## 使用工作树隔离子代理

子代理可以在自己的工作树中运行，这样并行编辑就不会冲突。要求 Claude"为您的代理使用工作树"，或通过在[自定义子代理](/en/sub-agents#supported-frontmatter-fields)的 frontmatter 中添加 `isolation: worktree` 来永久设置。每个子代理获得一个临时工作树，在子代理完成且没有更改时自动移除。

子代理工作树使用与 `--worktree` 相同的[基础分支](#选择基础分支)，因此除非 `worktree.baseRef` 设置为 `"head"`，否则它们从仓库的默认分支创建分支。

## 清理工作树

当您退出工作树会话时，清理取决于您是否进行了更改：

* **没有未提交的更改、没有未跟踪的文件且没有新提交**：工作树及其分支会自动移除。如果会话有[名称](/en/sessions#name-your-sessions)，Claude 会提示您，以便您可以保留工作树以供稍后使用
* **存在未提交的更改、未跟踪的文件或新提交**：Claude 提示您保留或移除工作树。保留会保留目录和分支，以便您稍后返回。移除会删除工作树目录及其分支，丢弃任何未提交的更改、未跟踪的文件和提交
* **非交互式运行**：使用 `--worktree` 与 `-p` 一起创建的工作树不会自动清理，因为没有退出提示。使用 `git worktree remove` 移除它们

因崩溃或中断运行而孤立的子代理工作树在启动时会被移除，前提是它们已超过您的 [`cleanupPeriodDays`](/en/settings#available-settings) 设置，且没有未提交的更改、未跟踪的文件和未推送的提交。您使用 `--worktree` 创建的工作树永远不会被此扫描移除。

## 手动管理工作树

要完全控制工作树位置和分支配置，请直接使用 Git 创建工作树。当您需要检出特定的现有分支或将工作树放在仓库外部时，这很有用。

在新分支上创建工作树：

```bash theme={null}
git worktree add ../project-feature-a -b feature-a
```

从现有分支创建工作树：

```bash theme={null}
git worktree add ../project-bugfix bugfix-123
```

在工作树中启动 Claude：

```bash theme={null}
cd ../project-feature-a && claude
```

列出您的工作树：

```bash theme={null}
git worktree list
```

完成后移除：

```bash theme={null}
git worktree remove ../project-feature-a
```

有关完整的命令参考，请参阅 [Git 工作树文档](https://git-scm.com/docs/git-worktree)。请记住在每个新工作树中初始化您的开发环境：安装依赖项、设置虚拟环境，或运行项目设置所需的任何操作。

## 非 git 版本控制

工作树隔离默认使用 git。对于 SVN、Perforce、Mercurial 或其他系统，请配置 [`WorktreeCreate` 和 `WorktreeRemove` 钩子](/en/hooks#worktreecreate)以提供自定义创建和清理逻辑。由于钩子替换了默认的 git 行为，使用 `--worktree` 时不会处理 [`.worktreeinclude`](#将-gitignore-文件复制到工作树)。请改为在钩子脚本内复制任何本地配置文件。

此 `WorktreeCreate` 钩子从 stdin 读取工作树名称，检出全新的 SVN 工作副本，并打印目录路径以便 Claude Code 将其用作会话的工作目录：

```json theme={null}
{
  "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` 钩子配对，以便在会话结束时清理。有关输入架构和移除示例，请参阅[钩子参考](/en/hooks#worktreecreate)。

## 另请参阅

工作树处理文件隔离。以下相关页面涵盖将工作委派到这些隔离检出中，以及在您创建的会话之间切换：

* [子代理](/en/sub-agents)：将工作委派给会话内的隔离代理
* [代理团队](/en/agent-teams)：自动协调多个 Claude 会话
* [管理会话](/en/sessions)：命名、恢复和切换对话
* [桌面并行会话](/en/desktop#work-in-parallel-with-sessions)：桌面应用中基于工作树的会话