跳到主要内容

本文为非官方中文翻译，内容以 OpenAI 官方英文文档为准。
官方来源：https://developers.openai.com/codex/app/worktrees

Worktrees

在 Codex app 中利用 Git worktree，让 Codex 并行工作

在 Codex app 中，worktree 让 Codex 能够在同一个项目中运行多个彼此独立的任务，而不会相互干扰。对于 Git 仓库，automations 会在专用的后台 worktree 上运行，因此不会与你正在进行的工作冲突。在非版本控制的项目中，automations 会直接在项目目录中运行。你也可以在 worktree 上手动启动线程，并使用 Handoff 在线程的 Local 与 Worktree 之间移动。

什么是 worktree​

worktree 仅适用于属于 Git 仓库一部分的项目，因为它们底层使用的是 Git worktrees。worktree 允许你创建仓库的第二份副本（“checkout”）。每个 worktree 都拥有仓库中每个文件的独立副本，但它们共享关于提交、分支等的相同元数据（.git 文件夹）。这使你可以并行检出并处理多个分支。

术语​

  • Local checkout：你创建的仓库。在 Codex app 中有时也简称为 Local。
  • Worktree：在 Codex app 中从你的本地 checkout 创建出的 Git worktree。
  • Handoff：在线程的 Local 与 Worktree 之间移动的流程。Codex 会处理所需的 Git 操作，以便安全地在它们之间移动你的工作。

为什么要使用 worktree​

  1. 与 Codex 并行工作，而不打扰你当前的 Local 设置。
  2. 当你专注于前台工作时，把后台工作排队执行。
  3. 之后在你准备好检查、测试或更直接协作时，将线程移到 Local。

快速开始​

worktree 需要一个 Git 仓库。请确保你选择的项目位于某个 Git 仓库中。

  1. 选择 “Worktree”

    在新线程视图中，在输入框下方选择 Worktree。 你还可以选择一个本地环境，以便为 worktree 运行 setup 脚本。

  2. 选择起始分支

    在输入框下方，选择作为 worktree 基础的 Git 分支。它可以是你的 main / master 分支、某个功能分支，或者是带有未暂存本地更改的当前分支。

  3. 提交你的提示词

    提交任务后，Codex 会根据你选择的分支创建一个 Git worktree。默认情况下，Codex 会在一种 “detached HEAD” 状态下工作。

  4. 选择接下来在哪里继续工作

    当你准备好时，你可以选择继续直接在 worktree 上工作，或者把线程 hand off 到你的本地 checkout。hand off 到本地或从本地 hand off，都会同时移动你的线程 和 代码，以便你能在另一个 checkout 中继续。

在 Local 和 Worktree 之间工作​

worktree 在外观和使用体验上与本地 checkout 很像。区别在于它们在你的工作流中的位置。你可以把 Local 视为前台，把 Worktree 视为后台。Handoff 让你可以在线程之间移动。

在底层，Handoff 会处理在两个 checkout 之间安全移动工作所需的 Git 操作。这一点很重要，因为 Git 只允许一个分支在同一时间于一个地方被检出。如果你在某个 worktree 上检出了一个分支，那么你不能同时在本地 checkout 中检出它，反之亦然。

在实践中，通常有两种常见路径：

  1. 只在 worktree 上工作。当你可以直接在 worktree 上验证更改时，这条路径最合适，例如你已经使用本地环境 setup 脚本安装了依赖和工具。
  2. 将线程 hand off 到 Local。当你想把线程带到前台时使用，例如你想在常用的 IDE 中检查更改，或者你的 app 只能运行一个实例。

选项 1：在 worktree 上工作​

如果你想连同你的更改一起只停留在 worktree 上，请使用线程页眉中的 Create branch here 按钮，将你的 worktree 转成一个分支。

接下来，你可以提交更改、将分支推送到远程仓库，并在 GitHub 上创建 pull request。

你可以使用页眉中的 “Open” 按钮在 worktree 中打开 IDE，也可以使用集成终端，或执行任何其他你需要在 worktree 目录中完成的操作。

带有分支控制和 worktree 详情的 worktree 线程视图

请记住，如果你在某个 worktree 上创建了一个分支，你就不能在任何其他 worktree（包括本地 checkout）中检出它。

选项 2：将线程 hand off 到 Local​

如果你想把一个线程带到前台，请点击线程页眉中的 Hand off，并将其移动到 Local。

当你想在常用的 IDE 窗口中查看更改、运行现有的开发服务器，或者在你日常已经使用的同一环境中验证工作时，这条路径非常适合。

Codex 会处理在线程于 worktree 与本地 checkout 之间安全移动时所需的 Git 步骤。

每个线程会随着时间始终保留同一个关联的 worktree。如果你之后再将线程 hand off 回某个 worktree，Codex 会把它放回同一个后台环境，这样你就可以从上次中断的地方继续。

将线程从 worktree 移动到 Local 的 Handoff 对话框

你也可以反向操作。如果你已经在 Local 中工作，并希望释放前台，请使用 Hand off 将线程移动到某个 worktree。当你希望 Codex 在后台继续工作，而你把注意力切回本地的其他事情时，这会很有用。

由于 Handoff 使用 Git 操作，任何属于你的 .gitignore 文件的文件都不会随线程一起移动。

高级细节​

Codex 管理的 worktree 和永久 worktree​

默认情况下，线程使用由 Codex 管理的 worktree。这些 worktree 旨在保持轻量且可随时丢弃。一个由 Codex 管理的 worktree 通常专用于一个线程，如果你之后再将该线程 hand off 回去，Codex 会把该线程返回到同一个 worktree。

如果你想要一个长期存在的环境，可以在侧边栏中项目的三点菜单里创建一个永久 worktree。这会将一个新的永久 worktree 作为独立项目创建出来。永久 worktree 不会被自动删除，而且你可以从同一个 worktree 启动多个线程。

Codex 如何为你管理 worktree​

Codex 会在 $CODEX_HOME/worktrees 中创建 worktree。起始提交将是你启动线程时所选分支的 HEAD 提交。如果你选择的是一个带有本地更改的分支，这些未提交的更改也会应用到 worktree 中。该 worktree 不会 作为分支被检出。它会处于 detached HEAD 状态。这样 Codex 就能创建多个 worktree，而不会污染你的分支。

分支限制​

假设 Codex 在某个 worktree 上完成了一些工作，而你选择使用 Create branch here 在其上创建一个 feature/a 分支。现在你想在本地 checkout 上试用它。如果你尝试检出这个分支，你会得到如下错误：

fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'

要解决这个问题，你需要在该 worktree 上检出另一个分支，而不是 feature/a。

如果你计划在本地检出该分支，请使用 Handoff 将线程移动到 Local，而不是试图在两个地方同时保持同一个分支被检出。

Git 会阻止同一个分支同时在多个 worktree 中被检出，因为一个分支表示的是单个可变引用（refs/heads/），它的含义是“某个工作树当前被检出的状态”。

当一个分支被检出时，Git 会把它的 HEAD 视为由该 worktree 所拥有，并期望像提交、重置、rebase 和 merge 这样的操作，以定义明确、串行化的方式推进该引用。允许多个 worktree 同时检出同一个分支，会导致到底由哪个 worktree 的操作来更新该分支引用变得含糊不清，并引发竞态条件，进而可能导致提交丢失、索引不一致，或冲突解决不明确。

通过强制执行“一个 worktree 只能对应一个分支”的规则，Git 保证每个分支都有一个唯一的权威工作副本，同时仍允许其他 worktree 通过 detached HEAD 或独立分支安全地引用相同的提交。

worktree 清理​

worktree 可能会占用大量磁盘空间。每个 worktree 都有自己的一套仓库文件、依赖、构建缓存等。因此，Codex app 会尽量将 worktree 的数量保持在合理范围内。

默认情况下，Codex 会保留你最近的 15 个由 Codex 管理的 worktree。如果你希望自行管理磁盘使用情况，也可以在设置中更改此限制或关闭自动删除。

Codex 会尽量避免删除仍然重要的 worktree。以下情况下，Codex 管理的 worktree 不会被自动删除：

  • 有一个置顶对话与其关联
  • 线程仍在进行中
  • 该 worktree 是永久 worktree

以下情况下，Codex 管理的 worktree 会被自动删除：

  • 你归档了关联的线程
  • Codex 需要删除较旧的 worktree 以保持在你配置的限制之内

在删除 Codex 管理的 worktree 之前，Codex 会保存其上的工作快照。如果你在其 worktree 已被删除后打开某个对话，你会看到恢复它的选项。

常见问题​

目前还不支持。Codex 会在 $CODEX_HOME/worktrees 下创建 worktree，这样它 就能一致地管理它们。

可以。使用线程标题中的 Hand off 在你的本地 checkout 和 worktree 之间移动线程。Codex 会处理安全地在不同环境之间移动线程所需的 Git 操作。如果你之后将线程交还给某个 worktree，Codex 会把它返回到同一个关联的 worktree。

即使底层的 worktree 目录已被删除，线程仍可能保留在你的历史记录中。对于 Codex 管理的 worktree，Codex 会在删除 worktree 之前保存一个快照，并在你重新打开关联线程时提供恢复选项。永久 worktree 不会在你归档其线程时被自动删除。