3.2 KiB
Pi Web 里的 Worktree
Pi Web 会把同一个 Git 项目的 main checkout 和 linked worktree 放在同一个项目下。你可以用它在不同分支之间切换工作目录，同时保留统一的会话列表。
什么时候会看到 Worktree 控件
当左上角选择的是 Git 仓库根目录时，项目选择器下面会出现 worktree 切换控件。
以下情况不会显示：
- 当前目录不是 Git 仓库。
- 当前目录在某个 Git 仓库里面，但不是仓库根目录。
- Git 无法读取这个仓库的 worktree 列表。
如果你在仓库子目录里，先从项目选择器打开仓库根目录，再管理 worktree。
切换 Worktree 会影响什么
worktree 切换器决定 Pi Web 接下来使用哪个 checkout。
它会影响：
- 从侧边栏新建的会话。
- 左侧 Explorer 浏览的文件。
- 从 Explorer 插入到输入框里的文件路径。
已有会话仍然按同一个 project root 分组。点击一个已有会话时，侧边栏会回到这个会话原本所在的 checkout。
新建 Worktree
在 worktree 菜单里选择 New worktree...，输入 branch name。
Pi Web 会把 checkout 放在：
<repo>-worktrees/<branch>
例如 main checkout 是：
/Users/alex/Documents/Workspace/pi-web
新建 codex/worktree-help 时，目录会是：
/Users/alex/Documents/Workspace/pi-web-worktrees/codex-worktree-help
如果这个 branch 已存在，Pi Web 会为它添加 worktree。如果 branch 不存在，Pi Web 会从当前 HEAD 创建这个 branch。
删除 Worktree
非 main worktree 右侧有删除按钮。它删除的是这个 checkout 目录。
删除 worktree 不会删除：
- Git branch。
- Pi Web 的历史会话。
- main checkout。
如果 worktree 里有未提交或未跟踪文件，Git 会拒绝删除。Pi Web 会再显示 force remove。force remove 会丢弃这个 checkout 里的未提交文件，只在确定不需要这些改动时使用。
会话和 Worktree 的关系
Pi Web 按 project root 分组会话，所以 main checkout 和 linked worktree 里的会话会显示在一起。
但每个会话仍然记得自己创建时的 working directory：
- 在某个 worktree 创建的会话，会继续使用那个 worktree path。
- 在 main checkout 创建的会话，会继续使用 main checkout。
- 如果某个 worktree 已被删除，它的历史会话仍会显示在项目下，方便你找回上下文。
常见问题
为什么我看不到 worktree 切换器？ 请确认当前选择的是 Git 仓库根目录。非 Git 目录和仓库子目录会显示一行轻提示，而不是切换器。
为什么某个 branch 不能创建 worktree？ Git 不允许同一个 branch 同时被多个 worktree checkout。你可以切到已有的 worktree，或者先删除那个 checkout。
Git 里还有已经消失的 worktree 记录怎么办？ Git 有时会保留 prunable worktree 记录。Pi Web 会过滤这些记录，不在切换器里显示。
Explorer 和当前聊天看起来不在同一个分支？ Explorer 跟随当前选择的 worktree；聊天跟随打开的会话。重新点击会话，可以把侧边栏切回这个会话所在的 checkout。