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

# Worktrees

> 自动设置 git worktrees，以并行运行 Cascade 任务

Devin Desktop 支持使用 git worktrees，在不干扰主工作区的情况下并行运行 Cascade 任务。

使用 worktrees 时，每个 Cascade 对话都会获得独立的 会话，使 Cascade 能够进行编辑、构建和测试代码，而不会影响你的主工作区。

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

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

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

<Note>
  目前，你只能在 Cascade 会话开始时切换到 worktree。一旦开始对话，就无法再切换到其他 worktree。
</Note>

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

<Frame>
  <img style={{ maxHeight: "500px" }} src="https://mintcdn.com/cognitionai/WE51TvKjsiyk1ZHl/desktop/assets/windsurf/worktree-merge.png?fit=max&auto=format&n=WE51TvKjsiyk1ZHl&q=85&s=574816f7a9d6a1b49b6d931c2ede8051" width="724" height="98" data-path="desktop/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` 钩子](./worktrees#setup-hook)，创建必要的符号链接，或将所需文件复制到预期位置。
</Warning>

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

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

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

`post_setup_worktree` 钩子会在每个 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 "Copied .env file"
fi

if [ -f "$ROOT_WORKSPACE_PATH/.env.local" ]; then
    cp "$ROOT_WORKSPACE_PATH/.env.local" .env.local
    echo "Copied .env.local file"
fi

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

exit 0
```

此钩子可确保每个工作树都会自动完成所需的环境配置并安装依赖。

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

Devin Desktop 在创建新的 worktree 时，会自动清理较旧的 worktree，以避免磁盘占用过高。每个工作区最多可有 **20** 个 worktree。

系统会根据 worktree 的最后访问时间进行清理——最旧的会先被移除。清理是按工作区分别进行的，以确保不同代码仓库中的 worktree 彼此独立。

此外，如果你手动删除某个 Cascade 对话，Devin Desktop 也会自动删除关联的 worktree。

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

默认情况下，Devin Desktop 不会在 SCM 面板中显示由 Cascade 创建的 worktrees。
你可以在设置中将 `git.showWindsurfWorktrees` 设为 `true`，以覆盖这一默认行为，并在 SCM 面板中显示这些 worktrees。