工作树
在 ChatGPT 桌面应用中，工作树让 Codex 可以在同一个项目中运行多个互不干扰的独立聊天。对于 Git 仓库，计划任务可以在专用的后台工作树中运行，因此不会与正在进行的工作冲突。在未使用版本控制的项目中，计划任务会直接在项目目录中运行。你也可以手动在工作树中开始聊天，并使用 Handoff 在 Local 和 Worktree 之间移动聊天。
工作树仅在 ChatGPT 桌面应用中的 Codex 内可用。在工作树中开始聊天前，请选择 Codex。
什么是工作树
Section titled “什么是工作树”工作树仅适用于 Git 仓库中的项目，因为其底层使用了 Git 工作树。工作树允许你创建仓库的第二个副本（“检出”）。每个工作树都有仓库中每个文件的独立副本，但它们共享有关提交、分支等信息的元数据（.git 文件夹）。这样，你就可以并行检出和处理多个分支。
- Local checkout：你创建的仓库。在 ChatGPT 桌面应用中有时简称为 Local。
- Worktree：在 ChatGPT 桌面应用中从 Local checkout 创建的 Git 工作树。
- Handoff：在 Local 和 Worktree 之间移动聊天的流程。Codex 会处理在两者之间安全移动工作所需的 Git 操作。
为什么使用工作树
Section titled “为什么使用工作树”- 与 Codex 并行工作，同时不影响当前的 Local 设置。
- 在专注于前台工作的同时，排队执行后台工作。
- 准备好更直接地检查、测试或协作时，再将聊天移入 Local。
工作树需要 Git 仓库。请确保你选择的项目位于 Git 仓库中。
-
选择“Worktree”
在新聊天视图中，在输入框下方选择 Worktree。你也可以选择一个本地环境，为工作树运行设置脚本。
-
选择起始分支
在输入框下方，选择作为工作树基础的 Git 分支。可以是
main/master分支、功能分支，也可以是当前包含未暂存本地更改的分支。 -
提交提示词
提交提示词后，Codex 会根据你选择的分支创建 Git 工作树。默认情况下，Codex 会在“分离 HEAD”状态下工作。
-
选择继续工作的位置
准备好后，你可以直接在工作树中继续工作，也可以将聊天移交给 Local checkout。移交到或移出 Local 时，聊天和代码都会一起移动，以便你在另一个检出中继续工作。
在 Local 和 Worktree 之间工作
Section titled “在 Local 和 Worktree 之间工作”工作树的外观和使用方式与 Local checkout 非常相似。区别在于它们在工作流程中的位置。你可以将 Local 理解为前台，将 Worktree 理解为后台。Handoff 让你可以在两者之间移动聊天。
在底层，Handoff 会处理在两个检出之间安全移动工作所需的 Git 操作。这一点很重要，因为 Git 只允许一个分支同时在一个位置被检出。如果你在工作树中检出了某个分支，就不能同时在 Local checkout 中检出该分支，反之亦然。
实际使用中，通常有两种路径：
- 只在工作树中工作。当你可以直接在工作树中验证更改时，这种方式最适合你，例如你已经通过本地环境设置脚本安装了依赖和工具。
- 将聊天移交给 Local。当你想将聊天带到前台时使用此方式，例如你想在常用的 IDE 中检查更改，或只能运行一个应用实例。
选项 1：在工作树中工作
Section titled “选项 1：在工作树中工作”如果你想只在工作树中继续处理更改，请使用聊天标题中的 Create branch here 按钮，将工作树转换为分支。
之后，你可以提交更改，将分支推送到远程仓库，并在 GitHub 上创建拉取请求。
你可以使用标题中的“Open”按钮在 IDE 中打开工作树，使用集成终端，或在工作树目录中执行其他所需操作。
请记住，如果你在工作树上创建了分支，就不能在任何其他工作树（包括 Local checkout）中检出该分支。
选项 2：将聊天移交给 Local
Section titled “选项 2：将聊天移交给 Local”如果你想将聊天带到前台，请在聊天标题中选择 Hand off，然后将其移至 Local。
当你想在常用的 IDE 窗口中查看更改、运行现有开发服务器，或在日常使用的同一环境中验证工作时，这种方式非常适合。
Codex 会处理在工作树和 Local checkout 之间安全移动聊天所需的 Git 步骤。
每个聊天会一直保留与其关联的同一个工作树。如果之后将聊天移回工作树，Codex 会将其返回到同一个后台环境，以便你从离开的地方继续工作。
你也可以反向操作。如果你已经在 Local 中工作，并希望释放前台，可以使用 Hand off 将聊天移至工作树。当你希望 Codex 在后台继续工作，同时将注意力转回本地的其他事务时，这种方式很有用。
由于 Handoff 使用 Git 操作，.gitignore 文件中的文件不会随聊天一起移动，除非 Codex 使用 .worktreeinclude 将它们复制到本地管理的工作树中。
高级详细信息
Section titled “高级详细信息”Codex 管理的工作树和永久工作树
Section titled “Codex 管理的工作树和永久工作树”默认情况下，聊天使用 Codex 管理的工作树。这些工作树旨在轻量且易于弃置。Codex 管理的工作树通常专用于一个聊天；如果你之后将该聊天移回工作树，Codex 会将其返回到同一个工作树。
如果你想要长期使用的环境，请通过侧边栏中项目的三点菜单创建永久工作树。这样会创建一个作为独立项目的新永久工作树。永久工作树不会自动删除，你可以从同一个工作树开始多个聊天。
Codex 如何管理工作树
Section titled “Codex 如何管理工作树”Codex 会在 $CODEX_HOME/worktrees 中创建工作树。起始提交是你开始聊天时所选分支的 HEAD 提交。如果你选择的分支包含本地更改，Codex 也会将未提交的更改应用到工作树中。工作树不会作为分支检出，而是处于分离 HEAD状态。这使 Codex 可以创建多个工作树，而不会污染你的分支。
将被忽略的本地文件复制到受管理工作树
Section titled “将被忽略的本地文件复制到受管理工作树”本地 Codex 管理的工作树从 Git checkout 开始，因此已跟踪的文件已经存在。如果你的仓库忽略了新工作树所需的本地设置文件，请在仓库根目录添加 .worktreeinclude 文件，并列出 Codex 创建受管理工作树时要复制的被忽略路径或 .gitignore 风格的模式。
可将此功能用于 Git 有意忽略的文件，例如 .env、.env.local 或 config/secrets.json。Codex 只会复制与 .worktreeinclude 匹配的被忽略文件，不会复制 Git 未跟踪的其他本地文件。不要列出已跟踪的文件。
Codex 会自动将被忽略的 AGENTS.override.md 复制到本地受管理工作树中，因此无需将其列在 .worktreeinclude 中。
.env.env.localconfig/secrets.jsonCodex 会跳过源符号链接，也不会覆盖新 checkout 中已经存在的文件。此行为适用于本地 ChatGPT 桌面应用管理的工作树，不适用于远程工作树或你通过命令行自行创建的 Git 工作树。
假设 Codex 在工作树中完成了一些工作，而你使用 Create branch here 在其中创建了 feature/a 分支。现在，你想在 Local checkout 中试用它。如果你尝试检出该分支，就会收到以下错误：
fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'要解决此问题，你需要在工作树中检出其他分支，而不是 feature/a。
如果你计划在 Local checkout 中检出该分支，请使用 Handoff 将聊天移入 Local，而不要试图让同一个分支同时在两个位置被检出。
为什么存在此限制
Section titled “为什么存在此限制”Git 不允许同一个分支同时在多个工作树中被检出，因为分支表示单个可变引用（refs/heads/<name>），其含义是“工作树当前检出的状态”。
当一个分支被检出时，Git 会将其 HEAD 视为由该工作树拥有，并期望提交、重置、变基和合并等操作以明确且串行化的方式推进该引用。如果允许多个工作树同时检出同一个分支，哪个工作树的操作会更新分支引用就会产生歧义和竞态条件，可能导致提交丢失、索引不一致或冲突解决方式不明确。
通过执行每个工作树只能对应一个分支的规则，Git 可以确保每个分支都有一个唯一的权威工作副本，同时仍允许其他工作树通过分离 HEAD 或独立分支安全地引用相同的提交。
工作树可能会占用大量磁盘空间。每个工作树都有自己的一组仓库文件、依赖项、构建缓存等。因此，ChatGPT 桌面应用会尝试将工作树数量保持在合理范围内。
默认情况下，Codex 会保留最近的 15 个 Codex 管理的工作树。如果你希望自行管理磁盘使用情况，可以在设置中更改此限制或关闭自动删除。
Codex 会尽量避免删除仍然重要的工作树。以下情况下，Codex 管理的工作树不会自动删除：
- 有固定的聊天与其关联
- 聊天仍在进行中
- 工作树是永久工作树
以下情况下，Codex 管理的工作树会自动删除：
- 你归档了关联的聊天
- Codex 需要删除较旧的工作树，以保持在你配置的限制之内
在删除 Codex 管理的工作树之前，Codex 会保存其中工作的快照。如果你在工作树被删除后打开聊天，就会看到恢复它的选项。
我可以控制工作树的创建位置吗？
Section titled “我可以控制工作树的创建位置吗？”可以。Codex 默认会在 $CODEX_HOME/worktrees 下创建受管理的工作树。若要选择其他位置，请打开 Settings > Worktrees，然后更改 Worktree root。
我可以在 Local 和 Worktree 之间移动聊天吗？
Section titled “我可以在 Local 和 Worktree 之间移动聊天吗？”可以。在聊天标题中使用 Hand off，即可在 Local checkout 和工作树之间移动聊天。Codex 会处理在不同环境之间安全移动聊天所需的 Git 操作。如果之后将聊天移回工作树，Codex 会将其返回到同一个关联的工作树。
删除工作树后，聊天会发生什么？
Section titled “删除工作树后，聊天会发生什么？”即使底层工作树目录被删除，聊天仍可以保留在历史记录中。对于 Codex 管理的工作树，Codex 会在删除工作树前保存快照；如果你重新打开关联的聊天，Codex 会提供恢复选项。归档聊天时，永久工作树不会自动删除。