> ## Documentation Index
> Fetch the complete documentation index at: https://docs.windsurf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 工作树

> 为并行 Cascade 任务自动设置 Git 工作树

Windsurf 支持使用 Git 工作树以并行运行 Cascade 任务，而不会影响你的主工作区。

使用工作树时，每个 Cascade 对话都有自己独立的会话环境，使 Cascade 可以进行编辑、构建和测试代码，而不会影响你的主工作区。

<div id="basic-worktree-usage">
  ## 基本 worktree 用法
</div>

开始使用 worktree 的最简单方式，是在 Cascade 输入框右下角将模式切换为 "Worktree"。

<Frame>
  <img style={{ maxHeight: "500px" }} src="https://mintcdn.com/codeium/U6QOrK-OfUtO4wfJ/assets/windsurf/worktree-toggle.png?fit=max&auto=format&n=U6QOrK-OfUtO4wfJ&q=85&s=8bb3e54349d5c84d4db81210a67ee931" width="873" height="224" data-path="assets/windsurf/worktree-toggle.png" />
</Frame>

<Note>
  目前，你只能在 Cascade 会话开始时切换到某个 worktree。会话一旦开始，就无法切换到不同的 worktree。
</Note>

当 Cascade 在 worktree 中完成文件修改后，你可以点击 "merge" 将这些更改合并回你的主工作区。

<Frame>
  <img style={{ maxHeight: "500px" }} src="https://mintcdn.com/codeium/U6QOrK-OfUtO4wfJ/assets/windsurf/worktree-merge.png?fit=max&auto=format&n=U6QOrK-OfUtO4wfJ&q=85&s=bb47b232dd861f3e37255b9b82fb18bc" width="724" height="98" data-path="assets/windsurf/worktree-merge.png" />
</Frame>

<div id="location">
  ## 位置
</div>

worktree 会按仓库名称组织存放在 `~/.windsurf/worktrees/<repo_name>` 目录下。

每个 worktree 都会被分配一个唯一的随机名称。

要查看当前活动的 worktree 列表，可以在仓库目录下运行 `git worktree list`。

<Warning>
  由于 worktree 位于不同于原始项目的目录中，**依赖相对路径的构建系统或工具**（例如 `../shared-lib` 引用、符号链接依赖，或通过路径解析的 monorepo 源码依赖）在 worktree 中可能会失效。如果你的项目在仓库根目录之外使用了相对路径，请配置一个 [`post_setup_worktree` hook](./worktrees#setup-hook) 来创建必要的符号链接，或将所需文件复制到预期的位置。
</Warning>

<div id="setup-hook">
  ## 设置 hook
</div>

每个 worktree 都包含一份仓库文件的副本，但不包括 `.env` 文件或其他未纳入版本控制的软件包。

如果你希望在每个 worktree 中包含额外的文件或软件包，可以使用 `post_setup_worktree` [hook](./hooks#post_setup_worktree) 将它们复制到该 worktree 目录中。

`post_setup_worktree` hook 会在每个 worktree 创建并完成配置后运行。它会在新的 **worktree** 目录中执行。

`$ROOT_WORKSPACE_PATH` 环境变量指向原始工作区路径，可用于访问文件或运行相对于原始仓库的命令。

<div id="example">
  ### 示例
</div>

在新建 worktree 时复制环境文件并安装依赖。

**配置**（位于 `.windsurf/hooks.json` 中）：

```json theme={null}
{
  "hooks": {
    "post_setup_worktree": [
      {
        "command": "bash $ROOT_WORKSPACE_PATH/hooks/setup_worktree.sh",
        "show_output": true
      }
    ]
  }
}
```

**脚本** (`hooks/setup_worktree.sh`):

```bash theme={null}
#!/bin/bash

# 从原始工作区复制环境文件
if [ -f "$ROOT_WORKSPACE_PATH/.env" ]; then
    cp "$ROOT_WORKSPACE_PATH/.env" .env
    echo "已复制 .env 文件"
fi

if [ -f "$ROOT_WORKSPACE_PATH/.env.local" ]; then
    cp "$ROOT_WORKSPACE_PATH/.env.local" .env.local
    echo "已复制 .env.local 文件"
fi

# 安装依赖
if [ -f "package.json" ]; then
    npm install
    echo "已安装 npm 依赖"
fi

exit 0
```

此钩子可确保每个 worktree 都能自动完成所需的环境配置并安装依赖项。

<div id="cleanup">
  ## 清理
</div>

Windsurf 在创建新的 worktree 时，会自动清理较旧的 worktree，以防止磁盘空间占用过多。每个工作区最多可以拥有 **20** 个 worktree。

worktree 会根据其上次访问时间进行清理——最久未访问的会被优先删除。清理由每个工作区单独进行，确保不同仓库中的 worktree 彼此独立。

此外，如果你手动删除某个 Cascade 会话，Windsurf 会自动删除与之关联的 worktree。

<div id="source-control-panel">
  ## 源代码管理面板
</div>

默认情况下，Windsurf 不会在 SCM 面板中显示由 Cascade 创建的工作树（worktree）。
你可以在设置中将 `git.showWindsurfWorktrees` 设置为 `true`，以覆盖该默认行为，并在 SCM 面板中显示这些工作树。