工作树

身份 非官方简体中文镜像

翻译状态 AI 翻译

来源版本 官方未提供

同步日期 2026-07-31

官方原文 learn.chatgpt.com

如需完整文档索引，请参阅 llms.txt。文档页面的 Markdown 版本可通过在页面后追加 .md 来获取 URL。

在 ChatGPT 桌面应用中，工作树让 Codex 可以在同一个项目中运行多个互不干扰的独立聊天。对于 Git 仓库，计划任务可以在专用的后台工作树中运行，因此不会与正在进行的工作冲突。在未使用版本控制的项目中，计划任务会直接在项目目录中运行。你也可以手动在工作树中开始聊天，并使用 Handoff 在 Local 和 Worktree 之间移动聊天。

Worktree 仅在 Codex 中的 ChatGPT 桌面应用中可用。选择 Codex 后，再在 worktree 中开始聊天。

什么是工作树

工作树仅适用于 Git 仓库中的项目，因为其底层使用了 Git 工作树。工作树允许你创建仓库的第二个副本（“检出”）。每个工作树都有仓库中每个文件的独立副本，但它们共享有关提交、分支等信息的元数据（.git 文件夹）。这样，你就可以并行检出和处理多个分支。

术语

• 本地 checkout：你创建的仓库。有时也简称为 本地 在 ChatGPT 桌面应用中。
• Worktree：一个 Git worktree ，它是在 ChatGPT 桌面应用中从你的本地 checkout 创建的。
• 交接：在本地与 Worktree 之间移动聊天的流程。 Codex 会处理在它们之间安全移动你的工作所需的 Git 操作。

为什么使用工作树

1. 与 Codex 并行工作，同时不影响当前的 Local 设置。
2. 在专注于前台工作的同时，排队执行后台工作。
3. 准备好更直接地检查、测试或协作时，再将聊天移入 Local。

开始使用

工作树需要 Git 仓库。请确保你选择的项目位于 Git 仓库中。

1. 选择“Worktree”

   在新聊天视图中，选择 Worktree ，它位于输入框下方。 也可以选择一个 本地环境 来为 worktree 运行设置脚本。

2. 选择起始分支

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

3. 提交你的提示词

   提交你的提示词， Codex 会基于你选择的分支创建一个 Git worktree。默认情况下， Codex 会在 “detached HEAD”中工作。

4. 选择继续工作的地方

   准备好后，你可以直接在 worktree 上继续工作，也可以将聊天交接到本地 checkout。交接到本地或从本地交接会移动你的聊天 和 代码，这样你就可以在另一个 checkout 中继续。

在 Local 和 Worktree 之间工作

工作树的外观和使用方式与本地检出非常相似。区别在于它们在工作流程中的位置。你可以将 Local 理解为前台，将 Worktree 理解为后台。Handoff 让你可以在两者之间移动聊天。

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

实际使用中，通常有两种路径：

1. 只在工作树中工作。当你可以直接在工作树中验证更改时，这种方式最适合你，例如你已经通过本地环境设置脚本安装了依赖和工具。
2. 将聊天移交给 Local。当你想将聊天带到前台时使用此方式，例如你想在常用的 IDE 中检查更改，或只能运行一个应用实例。

选项 1：在工作树中工作

如果你想只在包含这些更改的 worktree 上继续，请使用聊天标题中的 在此处创建分支 按钮，将你的 worktree 转换为一个分支。

在这里，你可以提交更改，将分支推送到远程仓库，并在 GitHub上打开 pull request。

你可以使用标题中的“打开”按钮将你的 IDE 打开到 worktree，使用集成终端，或执行任何需要从 worktree 目录完成的操作。

交互内容： CodexScreenshot 的动态演示请参阅页面顶部的官方原文链接。

请记住，如果你在工作树上创建了分支，就不能在任何其他工作树（包括本地检出）中检出该分支。

选项 2：将聊天移交给 Local

如果你想将聊天带到前台，请在聊天标题中选择 交接 并将其移动到 本地。

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

Codex 会处理在 worktree 与你的本地 checkout 之间安全移动聊天所需的 Git 步骤。

每个聊天会随着时间推移保留同一个关联的 worktree。如果你之后将聊天交接回 worktree， Codex 会把它返回到同一个后台环境，这样你就可以从上次离开的地方继续。

交互内容： CodexScreenshot 的动态演示请参阅页面顶部的官方原文链接。

你也可以反向操作。如果你已经在 Local 中工作，并希望释放前台，可以使用 Hand off 将聊天移至工作树。当你希望 Codex 在后台继续工作，同时将注意力转回本地的其他事务时，这种方式很有用。

由于 Handoff 使用 Git 操作，.gitignore 文件中的文件不会随聊天一起移动，除非 Codex 使用 .worktreeinclude 将它们复制到本地管理的工作树中。

高级详细信息

Codex-managed 和永久 worktree

默认情况下，聊天使用 Codex-managed worktree。这些 worktree 旨在轻量且可随时丢弃。一个 Codex-managed worktree 通常专用于一个聊天，并且 Codex 会在你之后将该聊天交接回那里时，把它返回到同一个 worktree。

如果你想要长期使用的环境，请通过侧边栏中项目的三点菜单创建永久工作树。这样会创建一个作为独立项目的新永久工作树。永久工作树不会自动删除，你可以从同一个工作树开始多个聊天。

Codex 如何管理工作树

Codex 会在 $CODEX_HOME/worktrees 中创建工作树。起始提交是你开始聊天时所选分支的 HEAD 提交。如果你选择的分支包含本地更改，Codex 也会将未提交的更改应用到工作树中。工作树不会作为分支检出，而是处于分离 HEAD状态。这使 Codex 可以创建多个工作树，而不会污染你的分支。

将被忽略的本地文件复制到受管理工作树

本地 Codex-managed worktree 从 Git checkout 开始，因此已跟踪文件已经存在。如果你的仓库忽略了新 worktree 所需的本地设置文件，请在仓库根目录添加一个 .worktreeinclude 文件，并列出在 .gitignore-style 创建托管 worktree 时要复制的已忽略路径或 Codex 模式。

可将此功能用于 Git 有意忽略的文件，例如 .env、.env.local 或 config/secrets.json。Codex 只会复制与 .worktreeinclude 匹配的被忽略文件，不会复制 Git 未跟踪的其他本地文件。不要列出已跟踪的文件。

Codex 会自动将被忽略的 AGENTS.override.md 复制到本地受管理工作树中，因此无需将其列在 .worktreeinclude 中。

.worktreeinclude

.env
.env.local
config/secrets.json

Codex 会跳过源符号链接，也不会覆盖新检出中已经存在的文件。此行为适用于本地 ChatGPT 桌面应用管理的工作树，不适用于远程工作树或你通过命令行自行创建的 Git 工作树。

分支限制

假设 Codex 在某个 worktree 上完成了一些工作，而你选择使用 feature/a 在其上创建一个 在此处创建分支分支。现在，你想在本地 checkout 上试用它。如果你尝试 checkout 该分支，会收到以下错误：

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

要解决此问题，你需要在工作树中检出其他分支，而不是 feature/a。

如果你计划在本地检出该分支，请使用 Handoff 将聊天移入 Local，而不要试图让同一个分支同时在两个位置被检出。

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

当一个分支被 checkout 时，Git 会将其 HEAD 视为由该 worktree 拥有，并期望提交、重置、rebase 和合并等操作以明确定义的串行方式推进该引用。允许多个 worktree 同时 checkout 同一个分支，会让哪个 worktree 的操作更新分支引用变得含糊，并产生竞态条件，可能导致提交丢失、索引不一致或冲突解决不明确。

通过强制一分支一 worktree 规则，Git 保证每个分支都有一个唯一权威的工作副本，同时仍允许其他 worktree 通过 detached HEADs 或单独的分支安全地引用同一批提交。

工作树清理

工作树可能会占用大量磁盘空间。每个工作树都有自己的一组仓库文件、依赖项、构建缓存等。因此，ChatGPT 桌面应用会尝试将工作树数量保持在合理范围内。

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

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

• 有固定的聊天与其关联
• 聊天仍在进行中
• 工作树是永久工作树

Codex-managed worktree 会在以下情况下自动删除：

• 你归档了关联的聊天
• Codex 需要删除较旧的工作树，以保持在你配置的限制之内

在删除一个 Codex-managed worktree 之前， Codex 会保存其上工作的快照。如果你在 worktree 被删除后打开聊天，会看到恢复它的选项。

常见问题

可以。 Codex 默认情况下， $CODEX_HOME/worktrees 会在 下创建托管 worktree。要选择其他位置，请打开 设置 > Worktree 并更改 Worktree 根目录。

可以。使用 交接 （在聊天标题中）在你的本地 checkout 和 worktree 之间移动聊天。 Codex 会处理在环境之间安全移动 聊天所需的 Git 操作。如果你之后将聊天交接回 worktree， Codex 会把它返回到同一个关联的 worktree。

即使底层 worktree 目录被 删除，聊天仍可以保留在你的历史记录中。对于 Codex-managed worktree， Codex 会在删除 该 worktree 前保存快照，并在你重新打开关联聊天时提供恢复选项。 当你归档其 聊天时，永久 worktree 不会被自动删除。