第37章 Worktrees：Orca 如何用 Git Worktree 实现并行开发

第37章 Worktrees

Worktrees：Orca 如何将每个功能或 Bug 转化为独立的 git worktree

Orca 原生支持 worktree。与在传统单检出目录中通过分支切换和暂存代码不同，Orca 为每个任务通过 git worktree 创建独立的磁盘副本。正是这一机制确保了并行 Agent 的安全性——它们永远不会互相干扰文件。

核心模型

每个仓库都有一个基础引用（base ref），通常是 origin/main。 每个 worktree 都有一个起始引用（start-from ref），即分支的基线。 每个 worktree 拥有独立的分支、磁盘文件和 Agent 终端。 删除 worktree 会同时移除目录和分支（需确认）。让 git 处理检出移除意味着删除操作不会阻塞聊天或文件操作。如果 git 无法完成检出移除，工作区仍会保留在列表中以便重试——在允许的情况下，Orca 提供强制删除选项。强制删除是一个分步控制：其菜单提供始终强制删除选项，该选择将记忆用于未来所有工作区删除操作。如果 git 因可能存在未合并提交而保留本地分支，Orca 可提供审查步骤——参见保留分支部分。

单功能生命周期

创建 — 填写任务名称，选择起始引用，可选添加 GitHub / Linear / Jira / GitLab 链接。 开发 — Agent 终端、编辑器标签页、浏览器标签页和终端面板均限定在此 worktree 内。 审查 — 对比起始引用的差异视图，使用 AI 差异注释和归属分析功能。 发布 — 提交、推送、开启 PR、等待检查——全部内联完成。 归档或删除 — 一键移除 worktree 和分支。

创建过程在后台运行 提交创建 worktree 对话框后立即关闭——git fetch 和 git worktree add 操作在后台继续，期间你仍可正常使用 Orca。新 worktree 出现在侧边栏，带有进度条，其标签页显示实时设置状态，直至检出完成并打开你选定的起始界面。选择 Agent 会将其作为首个标签页启动；选择空白终端则启动普通 shell。在创建过程中，你可以切换到其他 worktree、观察进度或在标签页面板中取消。在大仓库中创建依然快速，后台完成的创建不会把你切离当前工作区。如果创建失败，面板会显示错误并提供重试选项。

起始引用选择器 创建 worktree 时，新建工作区编辑器中的分支自控件设定起始引用，可以是：

仓库基础引用（最快路径）。 其他本地分支——适用于在审查中的 PR 上堆叠工作。 特定提交 SHA。 现有远程分支——Orca 将获取并检出该分支。

共享目录与 gitignored 文件 全新 worktree 是干净检出。位于 gitignored 路径中的依赖、缓存和局部密钥需要重新创建。

Orca 通过三种互补方式填补这一空白：

Worktree 共享路径（每仓库设置，位于设置 → 仓库）——这些路径从主检出复制到每个新 worktree（在 macOS 上尽可能使用 APFS 克隆复制，否则使用符号链接）。 orca.yaml 中的 worktree.sharedDirectories——仓库检入的 gitignored 共享目录列表，以相同方式（符号链接/共享，非复制）进行共享。适用于 node_modules 或 .cache 等大型可重建目录。条目必须存在于主检出中且被 gitignore；被跟踪或路径缺失的条目会被跳过。 仓库根目录下的 .worktreeinclude——复制到每个新 worktree 的 gitignored 文件或目录列表（非符号链接），使每个 worktree 拥有独立副本。典型条目：.env、.vscode 下的局部配置。允许空行和 # 注释。目前仅支持字面路径——通配符和否定规则会被跳过并警告。被跟踪、缺失或未 gitignore 的路径不会被复制。

orca.yaml 中的共享目录追加到用户级 Worktree 共享路径列表；绝不替换它。已共享/链接的路径不会从 .worktreeinclude 中重新复制。 ```yaml # orca.yaml (仓库根目录) worktree: sharedDirectories: - node_modules - .cache ``` ```text # .worktreeinclude (仓库根目录) .env .env.local .vscode/settings.json ```

创建对话框：项目、运行环境、Agent 和任务链接 创建工作区对话框对项目和运行环境使用预输入组合框：

输入以过滤；回车确认选中行。 项目始终在底部固定显示添加新项目——即使安装中暂无项目，创建也不会死胡同。 运行环境列出就绪的主机和配方，以及仍需在特定机器上设置项目的主机。在需设置的主机上，无需离开创建表单即可设置项目位置，然后浏览到现有检出/文件夹或将 Git 仓库克隆到该主机。Orca 自动选择新就绪的位置，以便你继续创建 worktree。断开的 SSH/远程主机可提供连接选项而不必选定为运行目标。添加主机在 SSH 或远程 Orca Server 目标中保持固定。 Agent 选择器（折叠或展开）可为你选择的 Agent 设置默认值，包括空白终端。 从名称字段链接 GitHub PR、Linear 问题、GitLab MR 或 Jira 问题（粘贴 Jira URL 或在 Jira 模式下搜索）。链接的问题显示在 worktree 卡片上。参见 Jira 项目抽屉。之后可从编辑 worktree 详情附加更多审查和任务。

参见运行 Orca 的方式。

表情符号工作区名称 在工作区名称字段中，可输入 Slack 风格的快捷代码（如 :rocket:）并从快捷代码建议气泡中选择。双击重命名 worktree、在编辑 worktree 详情中编辑或在 worktree 跳转面板（Cmd-J）中输入快捷代码时，也使用同一选择器。显示名称保留表情符号；当 Orca 推导 git 分支名称时，它将已知表情符号重写为可读的快捷代码（例如 🚀 变为 rocket）。跳转面板搜索通过该快捷代码派生的片段匹配表情符号命名工作区。

命名分支 默认情况下，Orca 根据你输入的工作区名称，或当工作区从相关项创建时根据链接的 GitHub PR、Linear/Jira 问题或 GitLab MR 推导新 worktree 的分支名称。若要设置显式分支名称，请展开创建 worktree 对话框中的高级抽屉，并在分支名称字段中输入（占位符 feature/my-branch）。

同一抽屉允许你从同一仓库中选择一个活动 worktree 作为新工作区的父工作区。这仅在 Orca 侧边栏中嵌套工作区；不改变 Git 历史或分支。Orca 排除已归档工作区及会创建循环的选择。

从 Linear 问题创建时，Orca 使用 Linear 为该问题生成的分支名称（如 Linear 提供）作为分支覆盖——与 Linear UI 中建议的名称相同——而非仅将问题标题 slug 化。

分支名称字段仅在从输入的工作区名称或基础分支创建时提供。当工作区绑定到跟踪的工作项时，分支从该工作项推导——链接的 GitHub PR 甚至在提交时会重新解析分支——因此 Orca 隐藏该字段以避免被静默忽略的覆盖。

侧边栏布局 默认情况下，侧边栏按项目分组 worktrees——顶级行为项目（一个项目 = 一个 git 仓库或相关集群），展开为你正在积极工作的 worktrees。标题栏有独立过滤输入框（与全局搜索分离），以便不离开侧边栏即可缩小列表。

侧边栏标题过滤菜单将主机和项目范围分组到共享的显示部分（主机和项目的子菜单行），然后是隐藏切换：

休眠工作区 — 每个项目的入口点/主工作区在此过滤下仍可见，当该检出不活动时项目行不会消失 除默认分支（仅在隐藏休眠开启时） — 在休眠清扫期间保留默认分支工作区可见；当休眠工作区已显示时，该子选项隐藏 默认分支工作区（主检出行） 自动化创建的工作区 CLI 创建的工作区 — 通过 orca worktree create 创建（悬停卡片可看到 Orca CLI 来源详情） 其他客户端工作区 — 当共享远程 Orca Server 有由另一对等客户端创建的工作区时，会出现隐藏其他客户端工作区；开启此选项可仅显示此设备创建的工作区。空的 Cmd-J 最近记录和数字快捷键遵循相同过滤；输入查询仍能找到隐藏行。 分离 HEAD 工作区 — 位于提交而非分支上的检出

活动过滤数量显示在过滤控件上；清除仅重置已开启的过滤。文本搜索和 worktree 跳转面板（Cmd-J）在输入查询后仍能触及仅被这些过滤隐藏的工作区——跳转面板也有自己的主机/项目过滤（Tab 键）。

添加包含多个 Git 仓库的父文件夹时，Orca 可单独导入所选仓库，或将其分组到一个项目组下。

侧边栏顶部的搜索按钮打开 worktree 跳转面板（Cmd-J）——相同界面，但通过点击操作，适用于不习惯键盘导航的用户。状态栏内联显示 Agent 活动；未读 worktrees 以粗体显示而非徽标。Orca 记忆重启间左侧边栏是否开启，从其他客户端显示远程工作区不会展开本地侧边栏部分。

你可以将 worktree 固定到其项目顶部，以保持长时间运行工作的可见性，右键点击 worktree 可显示归档/休眠/删除操作。要从键盘启动删除，悬停 worktree 或文件夹工作区，在 macOS 上按 Cmd-Shift-Backspace，在 Windows/Linux 上按 Ctrl-Shift-Backspace；正常确认对话框仍会出现。按住 Cmd（Linux/Windows 上为 Ctrl）点击可将 worktrees 添加到多选，或按住 Shift 选择连续范围——右键点击任一选定 worktree 会对选中的所有 worktrees 应用操作。仓库行本身可通过拖拽重新排序。拖拽行时，嵌套目标是宽阔稳定的放置区；在行上方或下方拖拽以重新排序，按 Escape 取消。

当 worktree 具有嵌套子 worktrees（例如来自编排或带父级的 worktree create）时，上下文菜单可提供带后代休眠（N）和带后代删除...。带后代休眠关闭选定工作区及同一项目、仓库和主机中所有已验证嵌套子项的活动面板——仅对具有活动终端或浏览器标签页的工作区执行休眠。带后代删除使现有的级联删除显式化并在后台运行，因此确认不会阻塞 Orca 其他部分。过时的血统链接、循环以及跨主机或仓库边界的子项会被排除。

父 worktree 在 N 个子项芯片下显示其嵌套子项；点击芯片显示或隐藏它们。要从键盘执行相同操作，请在设置 → 快捷键下分配切换子工作区。它作用于指针下的 worktree，或在未悬停时作用于活动 worktree，并完全执行该卡片芯片的功能。

双击侧边栏中的 worktree 标题可内联重命名。双击卡片其他位置仍打开完整编辑对话框。编辑 worktree 详情有一个链接部分，可将多个审查和任务附加到一个工作区——粘贴 GitHub、GitLab、Linear 或 Jira URL，或搜索已连接提供商。附加项分组为审查（拉取和合并请求）和问题与任务，并带有实时计数，工作区卡片以堆叠方式显示；链接必须属于工作区的仓库。对于主机断开的 SSH 工作区，卡片标题行可显示内联重连控件（参见 SSH worktrees）。

右键单击单个工作区并选择复制 worktree 名称，可复制 Orca 用于 worktree 选择器的规范名称。它遵循自定义名称、分支，然后文件夹回退的顺序，因此也适用于文件夹工作区和已清除自定义名称的工作区。

当你自己重命名工作区时，Orca 在 worktree 分支变更时保留该显示名称。清除自定义名称以恢复自动分支派生命名；Orca 生成的名称继续跟随分支。

资源管理器清理 需要跨设置审查工作区再移除时，请使用资源管理器 → 清理工作区。列表包括本地 worktrees、主 worktrees、文件夹工作区以及断开 SSH 主机上的工作区。文件夹工作区和项目组在此使用其保存的显示名称（例如，文档 → 发布说明）而非内部 ID，包括 Orca 重启时恢复会话后。选择移除前，可搜索、过滤或排序列表以检查每个工作区的状态、近期活动、大小、Git 状态和链接审查。

保留分支 批量删除工作区（侧边栏多选或资源管理器清理）仍会移除磁盘上的文件夹。如果 git 因可能包含未合并提交而拒绝删除本地分支，Orca 保留这些分支并显示如查看 N 个分支的提示。打开后列出保留的分支，你可强制删除部分并保留其他。未选定的分支保留在仓库中；工作区文件夹不会恢复。

多仓库项目组与文件夹工作区 导入包含多个 Git 仓库的父文件夹时，Orca 可在侧边栏中将这些仓库分组到一个项目组下。每个项目组暴露一个文件夹工作区流程——类似 worktree 的入口，位于父文件夹级别，并将其任务源绑定到下层其中一个仓库，因此尽管工作区本身在侧边栏中与同级分组，单个功能的 GitHub/GitLab/Linear/Jira 任务界面仍保持在正确的仓库上。

创建时，悬停侧边栏中项目组的标题行并点击 + 操作（工具提示：为组创建工作区）。组对话（创建文件夹工作区）要求你选择工作区任务源的源项目，命名工作区，并可选附加链接问题或 PR。提交后，文件夹工作区出现在项目组下，与常规仓库范围 worktrees 并列。

删除项目组时，Orca 还提供复选框在同一操作中移除组包含的项目（底层仓库注册）——因此清理不再使用的集群只需一次确认而非多次。

使用普通 git 每个 Orca worktree 都是真正的 git worktree。你可以打开终端并使用 git status、git rebase、git cherry-pick 等任何操作——Orca 在下一次渲染时捕获变更。

你用 git worktree add 自行创建的 worktrees 在显示于 Orca 前保持外部状态。如果仓库隐藏它们，侧边栏显示隐藏 worktrees 卡片。点击打开非 Orca worktrees，然后选择要在侧边栏中显示的工作区。

在设置 → 常规 → 工作区中，为外部 worktree 源设置全局默认：Claude Code worktrees、GSD worktrees、其他位置，以及你添加的任意自定义绝对路径位置。这些默认值应用于该主机上当前和未来的 worktrees；新的全局自定义根目录默认隐藏。在项目非 Orca worktrees 对话框中，可为该项目覆盖源或返回全局设置，然后搜索并恢复单个隐藏 worktrees。