Git worktree 为 Paneflow 中的并行任务提供独立的跟踪文件和分支。 每个 checkout 可以有自己的面板和智能体会话，仓库历史仍在本机共享。 分离 checkout 不会消除合并冲突，也不会隔离运行中的程序。
Paneflow 创建和移除受管理的 worktree。移除前会为磁盘上的未提交文件 创建快照，请先保存编辑器 buffer。忽略的本地文件和秘密信息需要另行 处理，详见下文。
什么是 worktree
worktree 只存在于位于 Git 仓库中的项目，因为 Paneflow 底层使用的就是 Git
worktree。worktree 是仓库的第二份副本（"检出"）。它有每个文件的独立副本，但与
主检出共享关于提交、分支和远程的同一份元数据（.git 文件夹）。正因如此，你可
以同时检出并处理多个分支。
术语
- 项目检出： 你作为 workspace 打开的那个仓库，也就是项目文件夹指向的位置。
- 受管 worktree： Paneflow 从该检出创建、并替你清理的 Git worktree。
- 快照： Paneflow 在移除 worktree 前，根据磁盘上未提交的文件生成的提交。 未保存的编辑器 buffer 和被忽略的文件不在这项保证范围内。
为什么使用 worktree
- 让一个 agent 做功能、另一个修 bug，各在自己的分支上，不触碰项目检出。
- 把耗时的任务留在后台，你专注于前台。
- 在会话的 Changes 标签页中阅读 diff，不触碰项目的 checkout。
开始使用
worktree 需要 Git 仓库。请确认你打开的项目位于仓库中。
在新分支上打开 pane
- 添加一个 pane。"New pane" 面板打开，agent 列表上方有一行分支。
- 打开分支行，选择 New branch…。
- 输入分支名，或留空以 detached 方式开始。
- 在 from 中选择起点分支或提交。默认是项目当前所在的分支。
- 保持 Worktree 开关打开。
- 选择用什么打开：终端、Claude Code、Codex、OpenCode，或你配置的任意启动器。
Paneflow 从你选的起点创建分支及其 worktree，把标签页绑定到该 worktree，并在那 里打开 pane。标签页显示分支名，agent 在 worktree 目录内启动。
同样的流程还出现在另外两处：
- 标签页的右键菜单为已有标签页提供 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 创建在哪里吗？
可以。在 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。
两个任务，再进行一次集成
在 Paneflow 0.17.4 的临时 Git 项目中，从已提交的基准开始。 按上文 New branch... 流程启用 Worktree：
- 从同一基准创建
feat/api-validation和test/api-validation， 分别用于实现和测试。启动智能体前确认每个标签页的路径与分支。 - 明确各任务负责的文件，开发服务器使用不同端口。在对应 checkout 安装依赖。主 checkout 的未提交修改不会成为新 worktree 的跟踪文件； 若两项任务都需要它们，应先提交所需基准。
- 保存后查看相对各自
HEAD的 Changes，再提交并用 Git 审查完整 分支 diff。Changes 不等于从 merge-base 开始的审查。 - 在选定的集成 checkout 中整合已审查提交，解决冲突并运行相关测试。 有用工作尚未保留前，不要移除任一 checkout。
历史、remote 和分支引用共享。端口、数据库、网络和用户权限不隔离。
.worktreeinclude 可复制本地秘密信息，请按任务选择文件。
Worktree 不是安全沙箱。
已打开分支、非 Git 项目和未保存编辑
已检出的分支会复用现有 checkout，不会再创建独立副本。先确认路径， 再判断隔离程度。非 Git 项目没有受管理 Git worktree 流程，可使用 当前目录，或明确决定初始化 Git。
切换或移除 checkout 前，应保存或明确放弃编辑器 buffer。快照读取 磁盘文件，不读取未保存文本。智能体仍在主 checkout 工作时也会拒绝 切换。Git 因覆盖文件风险拒绝切换时，保留文件并解决原因，不要强制清理。