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 中与其他 worktree 并排阅读结果，无需检出任何 东西。
开始使用
worktree 需要 Git 仓库。请确认你打开的项目位于仓库中。
在新分支上打开 pane
- 添加一个 pane。"New pane" 面板打开，agent 列表上方有一行分支。
- 打开分支行，选择 New branch…。
- 输入分支名，或留空以 detached 方式开始。
- 在 from 中选择起点分支或提交。默认是项目当前所在的分支。
- 保持 Worktree 开关打开。
- 选择用什么打开：终端、Claude Code、Codex、OpenCode，或你配置的任意启动器。
Paneflow 从你选的起点创建分支及其 worktree，把标签页绑定到该 worktree，并在那 里打开 pane。标签页显示分支名，agent 在 worktree 目录内启动。
同样的流程还出现在另外三处：
- Launch Pad 有 "New branch" 输入框和同样的 "From" 选择器。
- 标签页的右键菜单为已有标签页提供 New branch…。
paneflow up和 flow 接受worktree与from字段；见 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，每个仓库一个子目
录，每个分支一个目录：
~/.paneflow/worktrees/
paneflow-05926cc4/
feat-agents-browser/
fix-login/检出本身不会被写入任何东西。让 Paneflow 认出自己 worktree 的标记位于该
worktree 自己的 Git 元数据中，所以 git status 保持干净，标记也随 worktree 一
起消失。
在 Settings > Worktrees 中修改根目录，或在 paneflow.json 中设置
worktrees.dir。新根目录对之后创建的 worktree 生效；在旧根目录下创建的
worktree 留在原处继续工作，并仍在列表中。
把被忽略的本地文件复制进新 worktree
新 worktree 从 Git 检出开始，所以已跟踪文件已经就位。被 Git 忽略的文件则没
有，而 worktree 往往需要其中几个才能运行：.env、.env.local、本地的密钥文
件。
在仓库根目录添加 .worktreeinclude 文件，列出要复制的被忽略路径，每行一个，
相对根目录。目录也可以，末尾的 / 可有可无，# 开始一行注释。
# .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 无需检出即可读取 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。