跳转至

文档 / 模型 / Worktrees

Orca 原生支持 worktree。与其在同一个检出中分支和暂存，不如让每个任务通过 git worktree 获得仓库在磁盘上的独立副本。这正是并行代理安全的原因——它们永远不会互相覆盖文件。

模型

  • 每个仓库都有一个基础引用（通常为 origin/main）。
  • 每个工作树都有一个起始引用——即它所基于的分支点。
  • 每个工作树都有自己的分支、磁盘上的独立文件，以及自己的代理终端。
  • 删除工作树会同时删除目录和分支（需确认）。如果 git 因为可能仍有未合并提交而保留本地分支，Orca 可以提供审阅步骤——参见保留的分支。

按功能的生命周期

  1. 创建 — 任务名称、起始引用选择器，可选的 GitHub / Linear / Jira / GitLab 链接。
  2. 工作 — 代理终端、编辑器标签页、浏览器标签页和终端窗格都限定在此工作树范围内。
  3. 审阅 — 相对于起始引用的差异视图、Annotate AI Diff、Attribution。
  4. 发布 — 提交、推送、打开 PR、等待检查——全部内联完成。
  5. 归档或删除 — 单击即可删除工作树和分支。

创建在后台运行

提交“创建工作树”对话框后会立即关闭它——git fetch 和 git worktree add 操作会在后台继续，同时你可以继续使用 Orca。新工作树会出现在侧边栏中，并带有进度行；工作树标签页会实时显示设置状态，直到检出完成并切换到终端。在创建进行中时，你可以切换到其他工作树、查看进度，或从标签页内面板中取消。如果创建失败，面板会显示错误并提供“重试”。

起始引用选择器

创建工作树时，你需要选择从何处分支。可以是：

  • 仓库的基础引用（快速路径）。
  • 另一个本地分支——适用于在审阅中的 PR 之上堆叠工作。
  • 特定的提交 SHA。
  • 现有远程分支——Orca 会获取并检出它。

共享目录与被 git 忽略的文件

一个全新的工作树是一次干净的检出。位于被 git 忽略路径中的依赖、缓存和本地密钥，在你重新创建它们之前都会缺失。

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

  1. 工作树共享路径（按仓库设置，位于“设置 → 仓库”）——路径会从主检出物化到每个新工作树中（在 macOS 上尽可能使用 APFS 克隆复制，否则使用符号链接）。
  2. orca.yaml 中的 worktree.sharedDirectories —— 仓库中已检入的被 git 忽略的目录列表，以相同方式共享（符号链接/共享，而非复制）。请将其用于大型可重建目录树，例如 node_modules 或 .cache。条目必须在主检出中作为目录存在，并且被 git 忽略；被跟踪或不存在的路径会被跳过。
  3. 仓库根目录下的 .worktreeinclude —— 要复制（而非符号链接）到每个新工作树的被 git 忽略的文件或目录列表，使每个工作树拥有自己的副本。典型条目：.env、.vscode/ 下的本地配置。允许空行和 # 注释。目前仅支持字面量路径——通配符和取反会被跳过并给出警告。被跟踪、不存在或未被 git 忽略的路径不会被复制。

orca.yaml 中的共享目录会追加到按用户设置的工作树共享路径列表；它们永远不会替换该列表。已经共享/链接的路径不会从 .worktreeinclude 中再次复制。

# orca.yaml (repo root)
worktree:
  sharedDirectories:
    - node_modules
    - .cache

# .worktreeinclude (repo root)
.env
.env.local
.vscode/settings.json

“创建工作区”对话框为项目和运行于使用可输入过滤的组合框：

  • 输入以过滤；按 Enter 确认当前选中的行。
  • 项目始终将添加新项目固定在底部——当安装中还没有任何项目时，创建流程不会陷入死胡同。
  • 运行于列出就绪的主机和配方，以及仍需要在那台机器上设置项目的主机。对于需要设置的主机，无需离开创建表单即可选择设置项目位置，然后浏览到现有检出/文件夹，或将 Git 仓库克隆到该主机。Orca 会选中新就绪的位置，以便你继续创建工作树。已断开的 SSH / 远程主机可以提供连接，而不将其选为运行目标。添加主机会保持固定，用于 SSH 或 Remote Orca Server 目标。
  • 代理选择器（折叠或展开）可以为你在创建时选择的代理设置设为默认，包括空白终端。
  • 可以从名称字段关联 GitHub PR、Linear 议题、GitLab MR 或 Jira 议题（粘贴 Jira URL 或在 Jira 模式下搜索）。已关联的议题会显示在工作树卡片上。参见Jira 条目抽屉。

参见运行 Orca 的方式。

Emoji 工作区名称

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

命名分支

默认情况下，Orca 会根据你输入的工作区名称推导新工作树的分支名称；如果工作区是从关联的 GitHub PR、Linear/Jira 议题或 GitLab MR 创建的，则会根据该关联项推导。若要改为设置显式分支名称，请展开“创建工作树”对话框中的高级抽屉，并在分支名称字段中输入（占位符为 feature/my-branch）。

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

当你从 Linear 问题 创建时，Orca 会使用 Linear 为该问题提供的分支名称（如果 Linear 提供了）作为分支覆盖——Linear 在其 UI 中会建议的相同名称——而不是仅将问题标题转换为 slug。

分支名称字段仅在你从手动输入的工作区名称或基础分支创建时提供。当工作区关联到受跟踪的工作项时，分支从该工作项派生——关联的 GitHub PR 甚至在提交时重新解析分支——因此 Orca 会隐藏该字段，以避免出现被静默忽略的覆盖。

侧边栏默认按 项目 对工作树进行分组——顶层行是项目（一个项目 = 一个 git 仓库或相关集群），展开为你正在积极处理的工作树。标题栏有自己的过滤输入框（独立于全局搜索），因此你可以在不离开侧边栏的情况下缩小列表范围。

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

  • 休眠 工作区 — 每个项目的 入口 / 主 工作区在此过滤下保持可见，因此当该检出空闲时项目行不会消失
  • 除默认分支外（仅在 隐藏休眠 开启时）— 在休眠清理期间保持默认分支工作区可见；当休眠工作区已显示时，该子选项会被隐藏
  • 默认分支 工作区（主检出行）
  • 自动化创建 工作区
  • CLI 创建 工作区 — 通过 orca worktree create 创建（将鼠标悬停在卡片上可查看 Orca CLI 来源详情）
  • 其他客户端 工作区 — 当共享的 Remote Orca Server 存在由另一个已配对客户端创建的工作区时，会出现 隐藏其他客户端工作区；开启它可将此设备列表限制为你在此处创建的工作区。空的 Cmd-J 最近项和数字快捷键遵循相同过滤；输入查询仍能找到隐藏行。
  • 分离 HEAD 工作区 — 位于提交而非分支上的检出

活动过滤数量显示在过滤控件上；清除 仅重置已启用的过滤。文本搜索和 Worktree Jump Palette（Cmd-J）在你输入查询后，仍可访问仅被隐藏开关隐藏的工作区。Cmd-J 打开时会保留侧边栏的主机和项目范围；按 Tab 可调整其临时主机和单个仓库过滤。

当添加包含多个 Git 仓库的父文件夹时，Orca 可以分别导入所选仓库，或将它们归入一个项目组。

侧边栏顶部的 搜索 按钮会打开 Worktree Jump Palette（Cmd-J）——同一界面，面向不依赖键盘导航的用户提供点击操作。状态栏内联显示代理活动；未读工作树以加粗显示，而不是使用角标。

你可以将工作树固定到其项目顶部，以便长期运行的工作保持可见；右键单击工作树会显示归档 / 休眠 / 删除操作。要从键盘开始删除，将鼠标悬停在某个工作树或文件夹工作区上，然后在 macOS 上按 Cmd-Shift-Backspace，在 Windows / Linux 上按 Ctrl-Shift-Backspace；仍会显示常规确认对话框。按住 Cmd（Linux/Windows 上为 Ctrl）并单击，可将工作树添加到多选；或按住 Shift 选择连续范围——右键单击任意已选工作树会将操作应用到所选中的所有工作树。仓库行本身可通过拖拽重新排序。

当工作树具有嵌套子工作树时（例如来自编排或带父级的 worktree create），上下文菜单还可提供 连同后代休眠 (N) 和 连同后代删除…。连同后代休眠会关闭所选工作区以及同一项目、仓库和主机中每个已验证嵌套子工作区上的活动面板——只有具有活动终端或浏览器标签页的工作区会被休眠。连同后代删除使现有的级联删除变得明确。过期的谱系链接、循环，以及跨主机或仓库边界的子项会被排除。

在侧边栏中双击工作树标题可内联重命名。双击卡片其他位置仍会打开完整编辑对话框。在 编辑工作树详情 中，问题字段接受 GitHub 或 Linear（字段上显示芯片；粘贴 URL 可自动检测）。每个工作区只能关联一个问题——更改提供商或清空字段会解除之前关联的问题。对于主机已断开的 SSH 工作区，卡片标题行可显示内联重连控件（参见 SSH 工作树）。

资源管理器清理

当需要在删除前审查整个环境中的工作区时，使用 资源管理器 → 清理工作区。列表包括本地工作树、主工作树、文件夹工作区，以及位于已断开 SSH 主机上的工作区。搜索、过滤或排序列表，以检查每个工作区的状态、最近活动、大小、Git 状态和关联评审，然后再选择要删除的内容。

保留的分支

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

多仓库项目组与文件夹工作区

当你导入包含多个 Git 仓库的父文件夹时，Orca 可以在侧边栏中将这些仓库归入一个 项目组。每个项目组都提供一个 文件夹工作区 流程——一个类似工作树的条目，位于父文件夹级别，并将其任务源绑定到其下的某个仓库，因此某个功能的 GitHub/GitLab/Linear/Jira 任务界面仍会关联到正确的仓库，即使该工作区本身在侧边栏中与同级工作区分组。

要创建一个，将鼠标悬停在侧边栏中项目组的标题行上，然后单击 + 操作（工具提示：“为 group 创建工作区”）。创建对话框（“创建文件夹工作区”）会要求你选择工作区任务来源的源项目，为工作区命名，并可选择附加一个关联的 issue 或 PR。提交后，文件夹工作区会出现在项目组下方，并与常规仓库范围的 worktree 并列。

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

使用普通 git

每个 Orca worktree 都是真实的 git worktree。你可以在其中打开终端，并使用 git status、git rebase、git cherry-pick 以及任何其他命令——Orca 会在下次渲染时获取这些更改。

你自己使用 git worktree add 创建的 worktree 会保持为外部状态，直到你在 Orca 中显示它们。如果某个仓库隐藏了它们，侧边栏会显示一个 隐藏 worktree 卡片。单击它以打开 非 Orca worktree，然后为你希望显示在侧边栏中的 worktree 选择 显示。

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

如果你从 CLI 执行 git worktree remove，Orca 会在下次刷新该仓库时注意到这一点，并清理其自身状态。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 orca48/orca