codex-usage-guide/worktrees.html at master · WhoJay0609/codex-usage-guide · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
<!doctype html>
<html lang="zh-CN">
<head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Worktrees</title><!-- guide:theme-bootstrap:start -->
<script src="assets/theme.js"></script>
<!-- guide:theme-bootstrap:end -->
  <link rel="stylesheet" href="assets/site.css">  <!-- guide:metadata:start -->
<meta name="description" content="在 Codex Desktop 中用 Worktree 隔离并行任务，区分 Local environment 与 Local 主工作树，并安全交接。">
<meta name="guide-build" content="ee947e14a0a9">
<link rel="icon" href="favicon.svg" type="image/svg+xml">
<link rel="canonical" href="https://whojay0609.github.io/codex-usage-guide/worktrees.html">
<meta property="og:type" content="website">
<meta property="og:locale" content="zh_CN">
<meta property="og:site_name" content="Codex 使用指南">
<meta property="og:title" content="Worktrees">
<meta property="og:description" content="在 Codex Desktop 中用 Worktree 隔离并行任务，区分 Local environment 与 Local 主工作树，并安全交接。">
<meta property="og:url" content="https://whojay0609.github.io/codex-usage-guide/worktrees.html">
<meta property="og:image" content="https://whojay0609.github.io/codex-usage-guide/figures/social-preview.png">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image:alt" content="Codex 使用指南">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="Worktrees">
<meta name="twitter:description" content="在 Codex Desktop 中用 Worktree 隔离并行任务，区分 Local environment 与 Local 主工作树，并安全交接。">
<meta name="twitter:image" content="https://whojay0609.github.io/codex-usage-guide/figures/social-preview.png">
<meta name="twitter:image:alt" content="Codex 使用指南">
<!-- guide:metadata:end -->
</head>
<body>
  <!-- guide:header:start -->
<script src="assets/site-data.js"></script><a class="skip-link" href="#main-content">跳到正文</a><header class="topbar"><div class="topbar-inner"><a class="brand" href="index.html"><span class="brand-mark" aria-hidden="true"></span><span>Codex 使用指南</span></a><div class="topbar-actions"><label class="theme-control"><span class="sr-only">主题</span><select class="theme-select" id="theme-select" name="theme" aria-label="主题"><option value="light" selected>浅色</option><option value="dark">深色</option></select></label><span class="theme-status sr-only" aria-live="polite"></span><button class="search-trigger" type="button" aria-haspopup="dialog" aria-controls="site-search-dialog">搜索</button><button class="menu-toggle" type="button" aria-controls="global-nav" aria-expanded="false">目录</button></div></div></header><dialog class="search-dialog" id="site-search-dialog" role="dialog" aria-modal="true" aria-labelledby="site-search-title"><div class="search-dialog-panel"><div class="search-dialog-head"><p class="search-title" id="site-search-title">搜索全站</p><button class="search-close" type="button" aria-label="关闭搜索">关闭</button></div><label class="search-label" for="site-search-input">搜索标题、正文和可复用 prompt</label><input class="search-input" id="site-search-input" type="search" role="combobox" autocomplete="off" aria-autocomplete="list" aria-controls="site-search-results" aria-describedby="site-search-status" aria-expanded="false"><p class="search-message" id="site-search-status" aria-live="polite">输入关键词开始搜索。</p><ul class="search-results" id="site-search-results" role="listbox" aria-label="搜索结果"></ul></div></dialog>
<!-- guide:header:end -->
  <!-- guide:shell-open:start -->
<div class="toolbook-shell"><aside class="global-nav" id="global-nav" aria-label="全站导航"><section class="global-nav-group"><strong>开始</strong><a data-nav href="index.html">首页</a><a data-nav href="install-desktop.html">安装</a><a data-nav href="desktop-cli.html">Desktop</a></section><section class="global-nav-group"><strong>基础概念</strong><a data-nav href="codex.html">Codex</a><a data-nav href="git.html">Git</a><a data-nav href="worktrees.html" aria-current="page">Worktrees</a><a data-nav href="permissions.html">权限</a><a data-nav href="agents-md.html">AGENTS.md</a><a data-nav href="skills.html">Skills</a><a data-nav href="mcp.html">MCP</a><a data-nav href="subagents.html">Subagents</a><a data-nav href="goal.html">Goal</a></section><section class="global-nav-group"><strong>任务路径</strong><a data-nav href="workflows.html">任务</a><a data-nav href="daily-workflow.html">日常</a><a data-nav href="engineering.html">工程</a><a data-nav href="research.html">学术</a><a data-nav href="automation.html">定时任务</a></section><section class="global-nav-group"><strong>扩展与资料</strong><a data-nav href="compound-engineering.html">Compound</a><details class="global-nav-disclosure"><summary>Skills 仓库</summary><a data-nav href="skills-repositories.html">全部仓库</a><a href="skills-repositories.html#compound-engineering">Compound Engineering</a><a href="skills-repositories.html#mattpocock-skills">Matt Pocock skills</a><a href="skills-repositories.html#academic-research-skills-codex">ARS</a><a href="skills-repositories.html#aris-auto-claude-code-research-in-sleep">ARIS</a><a href="skills-repositories.html#refine-user-prompt">refine-user-prompt</a></details><a data-nav href="prompt-guidance.html">提示词</a><a data-nav href="resources.html">资料</a></section></aside><div class="toolbook-main"><nav class="breadcrumbs" aria-label="面包屑"><a href="index.html">首页</a><span aria-hidden="true">/</span><span>基础概念</span><span aria-hidden="true">/</span><span aria-current="page">Worktrees</span></nav><div class="page-freshness"><span>页面更新：<time datetime="2026-08-11">2026-08-11</time></span><span>事实核验：<time datetime="2026-08-11">2026-08-11</time></span></div><aside class="page-sources" aria-label="本页资料依据"><strong>本页依据</strong><a class="page-source-link external-link" href="https://learn.chatgpt.com/docs/environments/git-worktrees" target="_blank" rel="noopener noreferrer" referrerpolicy="no-referrer"><span class="external-link-indicator" data-search-exclude aria-hidden="true">↗</span><span class="sr-only" data-search-exclude>（外部链接）</span><span class="source-kind">OpenAI 官方</span>Git worktrees</a></aside><aside class="page-toc" aria-label="本页目录"><details><summary>本页目录</summary><nav><a class="toc-h2" href="#worktree-是什么">Worktree 是什么</a><a class="toc-h2" href="#什么时候用-不用">什么时候用 / 不用</a><a class="toc-h2" href="#在-desktop-中创建">在 Desktop 中创建</a><a class="toc-h3" href="#选择-worktree">1. 选择 Worktree</a><a class="toc-h3" href="#选择起始分支">2. 选择起始分支</a><a class="toc-h3" href="#提交独立任务">3. 提交独立任务</a><a class="toc-h3" href="#决定继续位置">4. 决定继续位置</a><a class="toc-h2" href="#local-worktree-与-handoff">Local、Worktree 与 Hand off</a><a class="toc-h2" href="#分支和文件边界">分支和文件边界</a><a class="toc-h3" href="#同一分支不能多处-checkout">同一分支不能多处 checkout</a><a class="toc-h3" href="#ignored-文件与-worktreeinclude">Ignored 文件与 .worktreeinclude</a><a class="toc-h2" href="#恢复与清理">恢复与清理</a><a class="toc-h2" href="#worktree-与-subagent-的区别">Worktree 与 Subagent 的区别</a><a class="toc-h2" href="#可复制示例">可复制示例（已选择 Desktop Worktree）</a><a class="toc-h2" href="#真实实例-并行页面修复">真实实例：并行页面修复</a></nav></details></aside>
<!-- guide:shell-open:end -->
  <main id="main-content"><section class="hero compact"><div class="hero-copy"><p class="hero-kicker">Git 隔离</p><h1>Worktrees</h1><p class="lead">在不打扰 Local 工作区的前提下，让 Codex Desktop 在同一仓库中运行独立任务；完成后留在 Worktree、创建分支，或通过 <strong>Hand off</strong> 回到 Local。</p></div></section>
    <div class="doc-layout"><article class="doc-content">
      <section class="content-block" id="what"><p class="section-kicker">是什么</p><span class="fragment-alias" id="heading-worktrees-1" data-canonical-fragment="worktree-是什么" aria-hidden="true"></span><h2 id="worktree-是什么">Worktree 是什么<a class="heading-permalink" data-heading-permalink data-search-exclude href="#worktree-是什么" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h2><p>Worktree 是同一个 Git 仓库的另一份 checkout。每个 Worktree 有独立的文件目录、索引和工作状态，但共享 commits、branches 等 Git 元数据。它适合隔离并行任务，不是虚拟机，也不是安全沙箱。</p><figure class="figure-card mermaid-card"><div class="mermaid">
flowchart TD
  A["同一个 Git 仓库"] --> B["Local: 前台工作区"]
  A --> C["Worktree A: 独立任务"]
  A --> D["Worktree B: 独立任务"]
  C --> E["Create branch here / PR"]
  D --> F["Hand off 到 Local"]
      </div><figcaption>文件目录彼此独立，Git 历史与分支元数据仍属于同一个仓库。</figcaption></figure><p><strong>官方事实：</strong>Codex Desktop 使用 Git worktrees 支持同一项目中的独立任务，并提供 Local 与 Worktree 之间的 <strong>Hand off</strong>。完整产品行为见 <a href="https://developers.openai.com/codex/app/worktrees" class="external-link" target="_blank" rel="noopener noreferrer" referrerpolicy="no-referrer"><span class="external-link-indicator" data-search-exclude aria-hidden="true">↗</span><span class="sr-only" data-search-exclude>（外部链接）</span>OpenAI Worktrees</a>。</p></section>

      <section class="content-block" id="when"><p class="section-kicker">何时使用</p><span class="fragment-alias" id="heading-worktrees-2" data-canonical-fragment="什么时候用-不用" aria-hidden="true"></span><h2 id="什么时候用-不用">什么时候用 / 不用<a class="heading-permalink" data-heading-permalink data-search-exclude href="#什么时候用-不用" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h2><ul class="mini-list"><li><strong>适合</strong><span>并行功能、试验性改动、后台任务，或 Local 已有未完成修改时。</span></li><li><strong>优先 Local</strong><span>单文件小修、需要复用当前开发服务器、只能启动一个应用实例，或必须频繁人工调试时。</span></li><li><strong>不要并行</strong><span>多个任务会修改同一 schema、共享 contract 或同一核心文件时，先拆依赖再创建 Worktree。</span></li><li><strong>前置条件</strong><span>项目必须位于 Git 仓库中；非 Git 项目不能创建 Worktree。</span></li></ul></section>

      <section class="content-block" id="desktop-start"><p class="section-kicker">Desktop 操作 · 已选择 Worktree</p><span class="fragment-alias" id="heading-worktrees-3" data-canonical-fragment="在-desktop-中创建" aria-hidden="true"></span><h2 id="在-desktop-中创建">在 Desktop 中创建<a class="heading-permalink" data-heading-permalink data-search-exclude href="#在-desktop-中创建" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h2><div class="steps"><article class="step"><span class="fragment-alias" id="heading-worktrees-4" data-canonical-fragment="选择-worktree" aria-hidden="true"></span><h3 id="选择-worktree">1. 选择 Worktree<a class="heading-permalink" data-heading-permalink data-search-exclude href="#选择-worktree" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h3><p>新建任务时，在输入框下方选择 <strong>Worktree</strong>。如项目配置了 <strong>Local environment</strong>（运行 setup scripts 的本地环境配置），可同时选择它；它不是 <strong>Local</strong> 前台／主 Worktree（main worktree），后者是当前打开的目录。</p></article><article class="step"><span class="fragment-alias" id="heading-worktrees-5" data-canonical-fragment="选择起始分支" aria-hidden="true"></span><h3 id="选择起始分支">2. 选择起始分支<a class="heading-permalink" data-heading-permalink data-search-exclude href="#选择起始分支" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h3><p>选择 main / master、功能分支，或当前含未提交修改的分支。Codex 以所选分支的 HEAD 为基线，并可把选中的本地未提交修改应用到新 Worktree。</p></article><article class="step"><span class="fragment-alias" id="heading-worktrees-6" data-canonical-fragment="提交独立任务" aria-hidden="true"></span><h3 id="提交独立任务">3. 提交独立任务<a class="heading-permalink" data-heading-permalink data-search-exclude href="#提交独立任务" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h3><p>写清目标、允许修改的文件、禁止触碰的范围和验证命令。Codex 创建 managed Worktree；<code>detached HEAD</code> 表示暂时直接停在某个提交上、没有绑定分支名，不会先污染分支列表；若要长期保留成果，再选择 <code>Create branch here</code>。</p></article><article class="step"><span class="fragment-alias" id="heading-worktrees-7" data-canonical-fragment="决定继续位置" aria-hidden="true"></span><h3 id="决定继续位置">4. 决定继续位置<a class="heading-permalink" data-heading-permalink data-search-exclude href="#决定继续位置" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h3><p>验证环境完整时可继续留在 Worktree；需要日常 IDE、现有服务器或人工联调时，通过 <strong>Hand off</strong> 移回 Local。</p></article></div></section>

      <section class="content-block" id="handoff"><p class="section-kicker">交接</p><span class="fragment-alias" id="heading-worktrees-8" data-canonical-fragment="local-worktree-与-handoff" aria-hidden="true"></span><h2 id="local-worktree-与-handoff">Local、Worktree 与 Hand off<a class="heading-permalink" data-heading-permalink data-search-exclude href="#local-worktree-与-handoff" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h2><div class="decision-table" aria-label="Worktree 后续路径"><div class="decision-row"><strong>留在 Worktree</strong><span>点击 <code>Create branch here</code></span><span>在该目录验证、commit、push 和创建 PR</span><span>该分支不能同时在 Local checkout</span></div><div class="decision-row"><strong>回到 Local</strong><span>点击 <code>Hand off</code></span><span>Codex 处理两个 checkout 间必要的 Git 操作</span><span>适合复用 IDE、服务器和本地调试状态</span></div><div class="decision-row"><strong>再回 Worktree</strong><span>再次使用 <code>Hand off</code></span><span>任务回到原先关联的 Worktree</span><span>继续保留该任务的后台环境</span></div></div></section>

      <section class="content-block" id="safety"><p class="section-kicker">边界</p><span class="fragment-alias" id="heading-worktrees-9" data-canonical-fragment="分支和文件边界" aria-hidden="true"></span><h2 id="分支和文件边界">分支和文件边界<a class="heading-permalink" data-heading-permalink data-search-exclude href="#分支和文件边界" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h2><div class="bento"><article class="card span-6 dark-card"><span class="fragment-alias" id="heading-worktrees-10" data-canonical-fragment="同一分支不能多处-checkout" aria-hidden="true"></span><h3 id="同一分支不能多处-checkout">同一分支不能多处 checkout<a class="heading-permalink" data-heading-permalink data-search-exclude href="#同一分支不能多处-checkout" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h3><p>Git 不允许同一分支同时被多个 Worktree checkout。若准备在 Local 接管，不要手动抢占该分支；优先使用 <strong>Hand off</strong>，或先让原 Worktree 切到其他分支。</p></article><article class="card span-6"><span class="fragment-alias" id="heading-worktrees-11" data-canonical-fragment="ignored-文件与-worktreeinclude" aria-hidden="true"></span><h3 id="ignored-文件与-worktreeinclude">Ignored 文件与 .worktreeinclude<a class="heading-permalink" data-heading-permalink data-search-exclude href="#ignored-文件与-worktreeinclude" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h3><p>被 <code>.gitignore</code> 忽略的文件不会自然出现在新 checkout。Codex managed Worktree 可通过仓库根目录的 <code>.worktreeinclude</code> 复制必要文件；只列运行所需项，并谨慎对待 <code>.env</code>、密钥和本地配置。</p><pre><code># .worktreeinclude
.env.local
config/local.json</code></pre></article></div><p><strong>不是安全沙箱：</strong>Worktree 仍可能共享 credentials、Git 元数据、后台进程、端口、数据库和外部服务。目录隔离不能替代权限控制、互斥写域或服务级隔离。</p></section>

      <section class="content-block" id="cleanup"><p class="section-kicker">生命周期</p><span class="fragment-alias" id="heading-worktrees-12" data-canonical-fragment="恢复与清理" aria-hidden="true"></span><h2 id="恢复与清理">恢复与清理<a class="heading-permalink" data-heading-permalink data-search-exclude href="#恢复与清理" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h2><ul class="mini-list"><li><strong>Managed Worktree</strong><span>通常服务于单个任务，适合轻量、可回收的后台工作。</span></li><li><strong>Permanent Worktree</strong><span>从项目菜单创建为长期项目，不会因归档关联任务而自动删除。</span></li><li><strong>自动清理</strong><span>Codex 默认保留最近 15 个 managed Worktrees；可在 Settings → Worktrees 调整数量或关闭自动删除。</span></li><li><strong>恢复</strong><span>删除 managed Worktree 前会保存快照；以后打开关联任务时可以恢复。</span></li></ul><p>Worktree 会 checkout 已跟踪文件；被忽略或未跟踪的依赖目录、构建缓存和下载资产不会自动出现，需按项目规则准备。若多个 Worktree 各自生成或下载这些文件，磁盘占用仍可能增长。任务结束后确认分支、PR、验证证据和未提交改动都已妥善保存，再归档或清理。</p></section>

      <section class="content-block" id="relationship"><p class="section-kicker">协作关系</p><span class="fragment-alias" id="heading-worktrees-13" data-canonical-fragment="worktree-与-subagent-的区别" aria-hidden="true"></span><h2 id="worktree-与-subagent-的区别">Worktree 与 Subagent 的区别<a class="heading-permalink" data-heading-permalink data-search-exclude href="#worktree-与-subagent-的区别" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h2><div class="decision-table" aria-label="Worktree 与 Subagent 对比"><div class="decision-row"><strong>Worktree</strong><span>隔离目录与 Git 状态</span><span>一个任务拥有独立 checkout</span><span>不自动定义谁可以改什么</span></div><div class="decision-row"><strong>Subagent</strong><span>隔离上下文、责任与写域</span><span>一个代理只处理明确子任务</span><span>不自动获得独立 Worktree</span></div><div class="decision-row"><strong>组合使用</strong><span>Worktree 负责环境隔离</span><span>Subagent 负责执行边界</span><span>主线程负责依赖、冲突和最终集成</span></div></div><p>Subagent 的委派合同、推荐拆法和收口规则见 <a href="subagents.html#worktree-subagent">Subagents</a>；按依赖建立并行 lane 的方法见 <a href="engineering.html#issue-lanes">Issue lanes</a>。</p></section>

      <section class="content-block" id="examples"><p class="section-kicker">可复制 · Desktop Worktree 已选</p><span class="fragment-alias" id="heading-worktrees-14" data-canonical-fragment="可复制示例" aria-hidden="true"></span><h2 id="可复制示例">可复制示例（已选择 Desktop Worktree）<a class="heading-permalink" data-heading-permalink data-search-exclude href="#可复制示例" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h2><aside class="callout"><strong>适用范围：</strong>下面的请求适用于你已经在 Codex Desktop 新建任务时选择 <strong>Worktree</strong> 的路径，不要再次要求 Codex 创建 Worktree。若要手动运行 <code>git worktree add</code>，请改用 <a href="git.html#git-codex-prompt">Git 页的 CLI / 手动路径</a>。</aside><pre><code>请在独立 Worktree 中完成这个任务，不要影响当前 Local 工作区。

Base: 当前 main 的最新提交。
Goal: 修复首页卡片布局并补浏览器回归测试。
Writable scope: index.html、assets/site.css、对应测试。
Forbidden: 其他页面、远程 push、合并主分支。
Validation: 静态检查 + desktop/mobile 浏览器测试。
Hand off: 完成后返回 changed files、测试证据和未验证项；
需要复用 Local 开发服务器时先停止并建议 Hand off。</code></pre></section>

      <section class="content-block" id="real-example"><p class="section-kicker">真实实例</p><span class="fragment-alias" id="heading-worktrees-15" data-canonical-fragment="真实实例-并行页面修复" aria-hidden="true"></span><h2 id="真实实例-并行页面修复">真实实例：并行页面修复<a class="heading-permalink" data-heading-permalink data-search-exclude href="#真实实例-并行页面修复" aria-label="本节永久链接"><span aria-hidden="true">#</span></a></h2><p><strong>场景：</strong>Local 正在修改主题控件，同时另一项任务需要重写 Worktree 文档页。两项改动依赖不同文件，可以把文档任务放到独立 Worktree，保留 Local 的未提交主题修改。</p><div class="decision-table"><div class="decision-row"><strong>开始</strong><span>从包含主题改动所需基线的分支创建 Worktree</span><span>明确只改文档页、manifest 和测试</span><span>共享生成器若有重叠则保持串行</span></div><div class="decision-row"><strong>验证</strong><span>在 Worktree 内运行页面生成和浏览器测试</span><span>记录真实 diff 与未验证项</span><span>不触碰 Local 的工作状态</span></div><div class="decision-row"><strong>收口</strong><span>需要独立 PR 时 Create branch here</span><span>需要复用 Local 预览环境时 Hand off</span><span>最终由主线程处理集成与冲突</span></div></div></section>
    </article></div>
  </main>
<!-- guide:shell-close:start -->
<nav class="page-sequence" aria-label="前后页"><a rel="prev" href="git.html">← Git</a><a rel="next" href="permissions.html">权限 →</a></nav></div></div>
<!-- guide:shell-close:end --><footer class="footer"><p><strong>Codex 使用指南</strong></p><a class="button" href="permissions.html">下一页：权限</a></footer>
  <!-- guide:runtime:start -->
<script src="https://cdn.jsdelivr.net/npm/mermaid@11.14.0/dist/mermaid.min.js" integrity="sha384-1CMXl090wj8Dd6YfnzSQUOgWbE6suWCaenYG7pox5AX7apTpY3PmJMeS2oPql4Gk" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
<script src="assets/site.js"></script>
<!-- guide:runtime:end -->
</body></html>