如果需要将 worktree 放在其他位置，可以配置 [`WorktreeCreate` hook](#非-git-版本控制)。在另一个终端用不同名称再次运行命令，即可启动第二个隔离会话：

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

你也可以在会话中要求 Claude "work in a worktree"，它会通过 [`EnterWorktree`](https://code.claude.com/docs/en/tools-reference) 工具创建一个 worktree。进入 worktree 后，Claude 可以通过调用 `EnterWorktree` 并指定目标路径，直接切换到 `.claude/worktrees/` 下的另一个 worktree。之前的 worktree 保留在磁盘上不受影响。

**首次使用前需要信任确认：** 在某个目录下首次交互式使用 `--worktree` 之前，需要先运行一次 `claude` 来接受工作区信任对话框。如果尚未接受信任，`--worktree` 会报错退出并提示你先在该目录运行 `claude`。使用 `-p` 的非交互式运行会跳过[信任检查](https://code.claude.com/docs/en/security)，因此 `claude -p --worktree` 可以直接执行。

> **提示：** 将 `.claude/worktrees/` 添加到 `.gitignore`，这样 worktree 的内容不会在主 checkout 中显示为未跟踪文件。

### 选择基础分支

**Worktree 默认从仓库的默认分支（`origin/HEAD`）创建新分支，** 确保起始状态与远端一致。如果没有配置远端或 fetch 失败，则回退到当前本地 `HEAD`。如果希望始终从本地 `HEAD` 创建分支，可以在[设置](https://code.claude.com/docs/en/settings)中将 `worktree.baseRef` 设为 `"head"`。设为 `"head"` 后，新 worktree 会携带你未推送的 commit 和特性分支状态，适用于需要子代理在进行中的工作上操作的场景。该设置只接受 `"fresh"` 或 `"head"`，不支持任意 git ref：

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

如果需要完全控制 worktree 的创建方式，可以配置 [`WorktreeCreate` hook](https://code.claude.com/docs/en/hooks)，它会完全替代默认的 `git worktree` 逻辑。

## 将 gitignore 文件复制到 Worktree

**Worktree 是全新的 checkout，不包含主仓库中的未跟踪文件，** 如 `.env` 或 `.env.local`。要在 Claude 创建 worktree 时自动复制这些文件，可以在项目根目录添加 `.worktreeinclude` 文件。

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

以下 `.worktreeinclude` 会将两个 env 文件和一个 secrets 配置复制到每个新 worktree 中：

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

从已有分支创建 worktree：

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

列出所有 worktree：

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

完整命令参考见 [Git worktree 文档](https://git-scm.com/docs/git-worktree)。注意每个新 worktree 都需要初始化开发环境：安装依赖、设置虚拟环境，或运行项目所需的任何设置步骤。

## 非 git 版本控制

**Worktree 隔离默认基于 git。** 对于 SVN、Perforce、Mercurial 或其他系统，可以配置 [`WorktreeCreate` 和 `WorktreeRemove` hook](https://code.claude.com/docs/en/hooks) 来提供自定义的创建和清理逻辑。由于 hook 替代了默认的 git 行为，使用 `--worktree` 时不会处理 [`.worktreeinclude`](#将-gitignore-文件复制到-worktree)。请在 hook 脚本中自行复制所需的本地配置文件。

以下 `WorktreeCreate` hook 从 stdin 读取 worktree 名称，检出一份新的 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\"'"
          }
        ]
      }
    ]
  }
}