worktree 让你在同一个项目上运行多个 agent，而它们互不干扰。每个 agent 都有自
己的仓库检出，在自己的分支上，带着自己的 pane 和 agent 会话，而仓库、worktree
和命令都留在你的机器上。

这些 worktree 由 Paneflow 创建和删除。删除之前，它会把未提交的工作保存为快
照，之后可以恢复。

## 什么是 worktree

worktree 只存在于位于 Git 仓库中的项目，因为 Paneflow 底层使用的就是 Git
worktree。worktree 是仓库的第二份副本（"检出"）。它有每个文件的独立副本，但与
主检出共享关于提交、分支和远程的同一份元数据（`.git` 文件夹）。正因如此，你可
以同时检出并处理多个分支。

### 术语

- **项目检出：** 你作为 workspace 打开的那个仓库，也就是项目文件夹指向的位置。
- **受管 worktree：** Paneflow 从该检出创建、并替你清理的 Git worktree。
- **快照：** Paneflow 在删除 worktree 之前，用其未提交更改生成的一个提交，确保
  什么都不会丢。

### 为什么使用 worktree

- 让一个 agent 做功能、另一个修 bug，各在自己的分支上，不触碰项目检出。
- 把耗时的任务留在后台，你专注于前台。
- 之后在 [Review](/docs/review) 中与其他 worktree 并排阅读结果，无需检出任何
  东西。

## 开始使用

worktree 需要 Git 仓库。请确认你打开的项目位于仓库中。

### 在新分支上打开 pane

1. 添加一个 pane。"New pane" 面板打开，agent 列表上方有一行分支。
2. 打开分支行，选择 **New branch…**。
3. 输入分支名，或留空以 detached 方式开始。
4. 在 **from** 中选择起点分支或提交。默认是项目当前所在的分支。
5. 保持 **Worktree** 开关打开。
6. 选择用什么打开：终端、Claude Code、Codex、OpenCode，或你配置的任意启动器。

Paneflow 从你选的起点创建分支及其 worktree，把标签页绑定到该 worktree，并在那
里打开 pane。标签页显示分支名，agent 在 worktree 目录内启动。

<figure className="my-8 w-full">
  <img
    src="/images/worktrees-new-branch.webp"
    alt="Paneflow 的 New pane 面板及 New branch 表单：分支名输入框、from 选择器、Worktree 开关，以及用于打开的 agent 列表。"
    width={2099}
    height={1366}
    className="h-auto w-full rounded-3xl! border border-surface-border dark:hidden"
  />
  <img
    src="/images/worktrees-new-branch-dark.webp"
    alt="Paneflow 的 New pane 面板及 New branch 表单：分支名输入框、from 选择器、Worktree 开关，以及用于打开的 agent 列表。"
    width={2099}
    height={1366}
    className="hidden h-auto w-full rounded-3xl! border border-surface-border dark:block"
  />
</figure>

同样的流程还出现在另外三处：

- **Launch Pad** 有 "New branch" 输入框和同样的 "From" 选择器。
- 标签页的右键菜单为已有标签页提供 **New branch…**。
- `paneflow up` 和 flow 接受 `worktree` 与 `from` 字段；见
  [Scripting](/docs/scripting)。

### 复用已存在的分支

在分支行中选一个已有分支，或在 "New branch…" 中输入它的名字。如果该分支已在某
个 worktree 中检出，Paneflow 会复用那个 worktree。如果它没有在任何地方检出，
Paneflow 会为它创建一个 worktree。此时 "from" 起点会被忽略，因为分支已经有自
己的历史。

Git 只允许一个分支同时在一处检出。Paneflow 从不对抗这条规则：它复用现有检
出，而不是以 `'feature/a' is already used by worktree at …` 失败。

### 先 detached 开始，之后再命名分支

把分支名留空，Paneflow 会在你选的起点创建一个 detached 的 worktree，按起点提交
命名为 `<base>-<sha>`。当你还不确定这项工作是否值得一个分支时，这是合适的选
择。

值得的时候，右键标签页并选择 **Create branch here…**。Paneflow 在该 worktree 内
运行 `git switch -c`，所以未提交的更改原地不动。

## 改为切换项目检出

在 "New branch…" 表单中关闭 **Worktree** 开关，Paneflow 就会像 `git switch -c`
那样，原地把项目检出切换到该分支，而不是创建 worktree。pane 在仓库根目录打
开，受管列表中不会新增任何条目。

当你独自在仓库上工作、只想要一个分支而不想多一个文件夹时，就用它。Paneflow
把你最后的选择记在 `worktrees.for_new_branches` 中，开关会按你上次的状态打开。

切换检出会让使用它的每个 pane 脚下的文件发生变化，所以当有 agent 正在该检出中
工作时，Paneflow 会拒绝切换。worktree 正是为这种情况而存在的。

## worktree 存放在哪里

Paneflow 在 `~/.paneflow/worktrees`（Windows 上为
`%USERPROFILE%\.paneflow\worktrees`）下创建受管 worktree，每个仓库一个子目
录，每个分支一个目录：

```text
~/.paneflow/worktrees/
  paneflow-05926cc4/
    feat-agents-browser/
    fix-login/
```

检出本身不会被写入任何东西。让 Paneflow 认出自己 worktree 的标记位于该
worktree 自己的 Git 元数据中，所以 `git status` 保持干净，标记也随 worktree 一
起消失。

在 **Settings > Worktrees** 中修改根目录，或在 `paneflow.json` 中设置
`worktrees.dir`。新根目录对之后创建的 worktree 生效；在旧根目录下创建的
worktree 留在原处继续工作，并仍在列表中。

<figure className="my-8 w-full">
  <img
    src="/images/worktrees-settings.webp"
    alt="Paneflow 的 Settings > Worktrees 页面：worktree 根目录、自动删除开关、保留上限、受管 worktree 列表，以及快照区域。"
    width={2099}
    height={1366}
    className="h-auto w-full rounded-3xl! border border-surface-border dark:hidden"
  />
  <img
    src="/images/worktrees-settings-dark.webp"
    alt="Paneflow 的 Settings > Worktrees 页面：worktree 根目录、自动删除开关、保留上限、受管 worktree 列表，以及快照区域。"
    width={2099}
    height={1366}
    className="hidden h-auto w-full rounded-3xl! border border-surface-border dark:block"
  />
</figure>

### 把被忽略的本地文件复制进新 worktree

新 worktree 从 Git 检出开始，所以已跟踪文件已经就位。被 Git 忽略的文件则没
有，而 worktree 往往需要其中几个才能运行：`.env`、`.env.local`、本地的密钥文
件。

在仓库根目录添加 `.worktreeinclude` 文件，列出要复制的被忽略路径，每行一个，
相对根目录。目录也可以，末尾的 `/` 可有可无，`#` 开始一行注释。

```text
# .worktreeinclude
.env
.env.local
config/secrets.json
```

没有该文件时，Paneflow 会复制顶层的 `.env*` 文件以及存在的
`AGENTS.override.md`。worktree 中已存在的文件绝不会被覆盖。不要列出已跟踪的文
件；Git 已经带上它们了。

## 清理

worktree 占用磁盘空间：每个都带着自己的文件、依赖和构建缓存。Paneflow 会自行
把数量控制在合理范围。

默认情况下，Paneflow 保留最近的 15 个受管 worktree。在 **Settings > Worktrees**
中修改上限或关闭自动删除，或在 `paneflow.json` 中使用 `worktrees.keep_limit`
和 `worktrees.auto_remove`。

受管 worktree 会在以下情况自动删除：

- 你关闭了它所属的 workspace；
- Paneflow 需要清理最旧的 worktree 以不超过保留上限。

只要某个已打开 workspace 的标签页还在使用它，受管 worktree 就绝不会被自动删
除。分支也绝不会被删除：删除 worktree 只删除检出，你的提交仍在分支上。

你也可以在 **Settings > Worktrees** 或标签页的右键菜单中手动删除 worktree。
Paneflow 只删除自己创建的 worktree；你用 `git worktree add` 自己创建的不会被动。

## 快照

删除受管 worktree 之前，无论自动还是手动，Paneflow 都会把它的未提交工作保存为
快照：已跟踪文件的修改、新文件，以及 worktree 当时所在的分支。干净的 worktree
不会留下快照。

快照是存放在仓库 `refs/paneflow/snapshots/` 下的普通 Git 提交。它们不触碰你的
分支，永远不会被推送，需要时可以用 `git log refs/paneflow/snapshots/<name>` 查
看。

**Settings > Worktrees** 在 "Snapshots" 下列出它们：

- **Restore** 在原路径、同一分支上重建 worktree，把保存的更改以未提交状态放
  回，并再次复制你的 `.worktreeinclude` 文件。
- **Delete** 永久丢弃该快照。

删除一个你不再需要其更改的 worktree，是有意设计成两步操作的：先删除，再删除
快照。

## worktree 与 Review

[Review](/docs/review) 无需检出即可读取 worktree。把分支或 worktree 拖到 pane
边缘，就能对照你选的起点阅读它的 diff，最多六个并排。删除 worktree 也会把它
从 Review 中移除。

## 常见问题

### 我能控制 worktree 创建在哪里吗？

可以。在 Settings > Worktrees 或用 `worktrees.dir` 设置根目录。`~` 展开为你的
主目录，`PANEFLOW_HOME` 则移动整个 `~/.paneflow` 目录，包括 worktree。

### worktree 被删除后我的工作会怎样？

提交仍在分支上。未提交的更改进入快照，可在 Settings > Worktrees 中恢复。在
"New pane" 面板中再次选择该分支，就能从其已提交状态得到一个全新的 worktree。

### 我能在 worktree 和项目检出之间移动工作吗？

先在 worktree 上提交或 stash，然后把项目检出切换到该分支：通过关闭 Worktree
开关的 "New branch…" 表单，或用 `git switch`。只要分支仍在 worktree 中检出，
Git 就会拒绝，所以请先在 Settings > Worktrees 中删除那个 worktree。

### Paneflow 会动我自己创建的 worktree 吗？

不会。Paneflow 会在分支行中列出它们并在其中打开 pane，但绝不会删除不是它创建
的 worktree。

## 另请参阅

- [配置参考](/docs/configuration/schema#worktrees)：每个 `worktrees.*` 键。
- [Review](/docs/review)：并排阅读 worktree 的 diff。
- [Scripting](/docs/scripting)：`paneflow up` 中的 `worktree` 与 `from`。
- [设置](/docs/settings)：Worktrees 页面。