在 Codex 应用中，工作树（Worktrees）允许 Codex 在同一个项目中同时运行多个独立任务，而互不干扰。对于 Git 存储库，自动化任务在专用的后台工作树中运行，因此不会与您正在进行的工作发生冲突。在非版本控制的项目中，自动化任务直接在项目目录中运行。您也可以手动在工作树上启动线程，并使用“交接”（Handoff）功能在本地（Local）和工作树（Worktree）之间迁移线程。
什么是工作树
工作树仅适用于作为 Git 存储库一部分的项目，因为它们在底层使用了 Git worktrees。工作树允许您创建存储库的第二个副本（“检出”）。每个工作树都拥有存储库中所有文件的独立副本，但它们共享关于提交、分支等的相同元数据（.git 文件夹）。这使您能够并行检出并处理多个分支。
术语表
- 本地检出（Local checkout）：您创建的存储库。在 Codex 应用中有时简称为 本地（Local）。
- 工作树（Worktree）：在 Codex 应用中从您的本地检出中创建的 Git 工作树。
- 交接（Handoff）：在本地和工作树之间迁移线程的流程。Codex 会处理将工作安全迁移至另一端所需的 Git 操作。
为什么要使用工作树
- 在不干扰当前本地设置的情况下与 Codex 并行工作。
- 在您专注于前台任务的同时，将后台任务加入队列。
- 当您准备好进行检查、测试或更直接的协作时，将线程移回本地。
开始使用
工作树需要 Git 存储库。请确保您选择的项目位于存储库中。
-
选择“工作树”（Worktree）
在新的线程视图中，选择合成器下方的 Worktree。您可以选择一个本地环境来为工作树运行安装脚本。
-
选择起始分支
在合成器下方，选择工作树所基于的 Git 分支。这可以是您的
main/master分支、功能分支，或是带有未暂存本地更改的当前分支。 -
提交您的提示词
提交您的任务，Codex 将创建一个基于您所选分支的 Git 工作树。默认情况下，Codex 在 “分离头指针”（detached HEAD）状态下工作。
-
选择继续工作的位置
准备好后，您可以选择直接在工作树上继续工作，或将线程交接给本地检出。执行交接（无论是移入还是移出本地）都会迁移您的线程和代码，以便您在另一个检出中继续工作。
在本地和工作树之间切换
工作树的外观和操作与您的本地检出非常相似。区别在于它们在流程中的位置。您可以将本地视为前台，将工作树视为后台。交接功能允许您在两者之间迁移线程。
在底层，交接功能处理在两个检出之间安全迁移工作所需的 Git 操作。这一点至关重要，因为 Git 规定一个分支一次只能在一个地方被检出。如果您在一个工作树上检出了某个分支，则无法同时在本地检出中对其进行检出，反之亦然。
实际上，有两种常见的路径
- 仅在工作树上工作。当您可以直接在工作树上验证更改时，此路径最为有效。例如，如果您已使用本地环境安装脚本安装了依赖项和工具。
- 将线程交接给本地。当您希望将线程带到前台时使用此选项，例如：您希望在常用的 IDE 中检查更改，或者您的应用只能运行一个实例。
选项 1：在工作树上工作
如果您想让更改保留在工作树上，请使用线程标题中的 Create branch here（在此创建分支）按钮，将您的工作树转换为一个分支。
此后，您可以提交更改、将分支推送到远程仓库，并在 GitHub 上发起拉取请求（Pull Request）。
您可以使用标题中的“Open”按钮在 IDE 中打开工作树、使用集成终端，或执行任何您需要在工作树目录中完成的操作。
请记住，如果您在工作树上创建了分支，则无法在任何其他工作树（包括您的本地检出）中检出它。
选项 2：将线程交接给本地
如果您想将线程带到前台，请点击线程标题中的 Hand off，并将其移动到 Local。
当您想在常用的 IDE 窗口中阅读代码、运行现有的开发服务器或在日常使用的环境中验证工作时，此路径非常有效。
Codex 会处理在工作树和本地检出之间安全迁移线程所需的 Git 步骤。
每个线程在整个生命周期内都保持关联同一个工作树。如果您稍后将线程交接回工作树，Codex 会将其返回到同一个后台环境，以便您可以从中断处继续工作。
您也可以反向操作。如果您已经在本地工作并想腾出前台，请使用 Hand off 将线程移动到工作树。这在您希望 Codex 在后台继续工作，而您将注意力转向本地其他任务时非常有用。
由于交接功能使用 Git 操作，因此属于 .gitignore 文件中的任何文件都不会随线程一起迁移。
高级详情
Codex 管理的工作树与永久工作树
默认情况下，线程使用 Codex 管理的工作树。这些工作树旨在提供轻量且临时的体验。一个 Codex 管理的工作树通常专门用于一个线程，如果您稍后交接回来，Codex 会将该线程返回到同一个工作树中。
如果您需要一个长期运行的环境，请从侧边栏项目的三个点菜单中创建“永久工作树”（Permanent worktree）。这将创建一个新的永久工作树作为独立项目。永久工作树不会被自动删除，且您可以从同一个工作树启动多个线程。
Codex 如何为您管理工作树
Codex 在 $CODEX_HOME/worktrees 下创建工作树。起始提交将是启动线程时所选分支的 HEAD 提交。如果您选择了一个带有本地更改的分支，未提交的更改也会应用到工作树中。工作树不会以分支形式被检出，而是处于 分离头指针（detached HEAD）状态。这使得 Codex 能够创建多个工作树而不会污染您的分支。
分支限制
假设 Codex 在工作树上完成了某项工作，并且您选择使用 Create branch here 在其上创建了一个 feature/a 分支。现在，您想在本地检出中尝试该分支。如果您尝试检出该分支，将会收到以下错误：
fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'要解决此问题，您需要在工作树上检出另一个分支，而不是 feature/a。
如果您打算在本地检出该分支，请使用“交接”功能将线程移入本地，而不是试图同时在两个地方检出同一个分支。
为什么存在此限制
Git 防止同一个分支在多个工作树中被同时检出，因为分支代表了一个单一的可变引用（refs/heads/），其含义是工作树的“当前检出状态”。
当分支被检出时，Git 将其 HEAD 视为该工作树所拥有，并期望提交、重置、变基和合并等操作以定义明确的序列化方式推进该引用。如果允许多个工作树同时检出同一分支，则会在哪个工作树的操作更新分支引用上产生歧义和竞态条件，从而可能导致丢失提交、索引不一致或冲突解决不清。
通过执行“一个工作树对应一个分支”的规则，Git 确保每个分支都有一个权威的工作副本，同时仍允许其他工作树通过分离头指针或独立分支安全地引用相同的提交。
工作树清理
工作树可能会占用大量磁盘空间。每个工作树都有自己的一套存储库文件、依赖项、构建缓存等。因此，Codex 应用会尝试将工作树的数量保持在合理范围内。
默认情况下，Codex 会保留您最近使用的 15 个由 Codex 管理的工作树。如果您倾向于自行管理磁盘使用，可以在设置中更改此限制或关闭自动删除功能。
Codex 尝试避免删除仍然重要的工作树。由 Codex 管理的工作树如果满足以下条件，将不会被自动删除：
- 关联了固定的对话
- 线程仍在进行中
- 该工作树是永久工作树
由 Codex 管理的工作树会在以下情况被自动删除：
- 您归档了关联的线程
- Codex 需要删除旧的工作树以保持在您配置的限制内
在删除由 Codex 管理的工作树之前，Codex 会保存一份工作快照。如果您在工作树被删除后打开对话，您将看到恢复它的选项。
常见问题解答
我可以控制工作树的创建位置吗？
目前不可以。Codex 在 $CODEX_HOME/worktrees 下创建工作树，以便对其进行统一管理。
我可以在本地和工作树之间迁移线程吗？
是的。使用线程标题中的 Hand off 即可在本地检出和工作树之间迁移线程。Codex 会处理在环境间安全迁移线程所需的 Git 操作。如果您稍后将线程交接回工作树，Codex 会将其返回到同一个关联的工作树。
如果工作树被删除，线程会怎样？
即使底层工作树目录被删除，线程仍可保留在您的历史记录中。对于由 Codex 管理的工作树，Codex 在删除前会保存快照，并在您重新打开关联线程时提供恢复选项。永久工作树在归档线程时不会被自动删除。