很多开发者第一次看到 Codex 里的两个选项——“派生到本地”和“派生到新工作树”——都会下意识地把它理解成“要不要顺手建个 Git 分支”。这种理解不算全错，但离真正的区别还差得很远。
问题的关键在于：分支、工作树和本地派生，分别作用在 Git 的不同层面。 分支管理的是提交历史的分叉，工作树管理的是代码在磁盘上的独立检出，而“派生到本地”说的是让修改直接落到你当前正在使用的那份项目目录里。它们彼此相关，但并不是同一个概念。
如果这个边界没想清楚，实际开发里很容易出现几类典型问题：当前工作目录被 AI 改乱、实验性修改和正式开发互相污染、同一个仓库里来回切换上下文导致效率下降，甚至误以为“我已经开了分支，所以环境天然隔离了”。
这篇文章不打算只做名词解释，而是从 Git 的底层模型出发，把这三个概念彻底拆开，再讲清楚在 Codex 场景下该怎么选。
一、先把一个常见误区纠正：Git 分支并不等于独立工作空间
很多人之所以会误解 Codex 的这两个选项，本质上是因为把“分支”想象得太强了。
在 Git 里，分支首先是一个指向提交的可移动引用。你可以把它理解成一条开发线索的名字：main 指向稳定版本，feature 指向某个功能开发中的提交，hotfix 指向修复中的提交。这个模型的核心价值，是让同一套仓库历史可以沿着不同方向推进。
但这里有一个非常重要、却很容易被忽略的事实：默认情况下，不管你创建多少分支，你本地通常只有一份工作目录。
这意味着什么？意味着你切换分支时，真正被切换的是这份工作目录对应的检出内容。也就是说，分支解决的是“历史和版本线如何组织”的问题，而不是“你能不能同时拥有多个彼此独立的本地开发现场”。
这也是为什么很多人虽然知道怎么用 branch，却依旧会在这些场景里感到不顺手：
- 你正在主分支排查一个 bug，同时又想让 AI 试做一个重构方案；
- 你想保留当前未提交的现场，但又希望开一个干净环境验证另一条思路；
- 你不想反复 checkout，因为那会打断上下文、改掉编辑器状态、影响运行中的服务。
这些问题，单靠“创建分支”并不能优雅解决。因为分支是逻辑上的分叉，不等于磁盘上的隔离现场。
二、Codex 里的“派生到本地”到底在做什么
OpenAI 的官方文档把 Codex app 的新线程目标分成 Local 和 Worktree 两类：Local 直接在当前项目中工作，而 Worktree 会创建新的 Git worktree，让修改与常规项目隔离。官方还把 Local 与 Worktree 明确并列为两种不同的运行位置，而不是“是否创建分支”的简化开关。
放到实际体验里，“派生到本地”可以把它理解成：让 Codex 在你当前正在用的那份项目目录里继续干活。
这种模式的优点非常直接。
第一，它最省切换成本。你不用开新目录，不用重新启动依赖，不用再让 IDE 重新索引项目。对小改动、低风险修复、已经明确知道要改哪里的问题来说，这种模式非常顺手。
第二，它最贴近“结对编程”体验。因为 Codex 改的，就是你眼下这份代码。你看到的 diff、终端状态、运行环境和测试结果，全都和你当前上下文一致。
但它的问题也同样明显：Local 模式几乎不提供物理隔离。
一旦 Codex 的改动范围超出预期，或者你其实只是想“先让它试试看”，那这些修改就会直接进入你当前工作目录。哪怕你还没提交，它也已经和你手头正在做的事情混在一起了。对于 AI 辅助开发来说，这恰恰是高风险场景，因为 AI 很擅长一次性提出大改动，但这些改动并不总是值得直接落在主工作区里。
所以，“派生到本地”最适合的不是所有任务，而是这几类：
- 你已经在正确的目标分支上；
- 任务足够小，回滚成本低；
- 你希望 Codex 直接介入当前上下文，而不是另起炉灶；
- 你更在意速度，而不是隔离性。
一句话概括：它不是“新建一个开发空间”，而是“让 AI 直接接管你手头这份开发空间”。
三、“派生到新工作树”为什么不是“再建一个分支”那么简单
真正容易被低估的，是 Worktree。
OpenAI 的官方说明写得很清楚：Codex 的 Worktree 模式会创建新的 Git worktree，让修改和你常规项目保持隔离；你可以选择 worktree 基于哪条分支创建，也可以稍后把线程从 worktree 交还到本地检出继续工作。文档同时提到，Git 规则本身限制了同一条分支不能在两个检出位置同时被 checkout，因此 Codex 在 Local 与 Worktree 之间还提供了专门的 handoff 流程来安全移动工作。
这背后对应的其实是 Git 的一个高级能力：git worktree。
它解决的不是“有没有第二条开发线”，而是“能不能在同一个仓库下，同时拥有第二份、第三份彼此独立的检出目录”。
这是一个非常重要的思维转变。因为在传统理解里，很多人把开发现场想象成这样：一个仓库，一个目录，多个分支，来回切换。而 worktree 提供的是另一种模式：一个仓库，多个目录，每个目录各自绑定一条分支或一份检出状态，可以并行存在。
这意味着你可以把主项目留在原地继续工作，同时让 Codex 在另一个目录里：
- 尝试大规模重构；
- 验证一个风险不明的修复方案；
- 为同一个需求生成两套不同实现；
- 运行会污染依赖、缓存或构建产物的实验任务。
它的价值不只是“方便”，而是把逻辑隔离变成物理隔离。你不再需要用意志力记住哪些文件是试验改动，哪些是正式开发；也不需要为了切换任务，把当前目录来回 checkout 到不同分支。不同任务就是不同目录，不同目录就是不同现场。
官方的本地环境文档还特别提醒：worktree 运行在不同目录下，因此只会继承 Git 中已检入的文件，未纳入版本控制的依赖、生成物或本地文件可能不会自动存在，所以往往要配合 setup script 做初始化。这个细节也恰好说明，worktree 不是“虚拟分支”，而是真正独立的本地工作目录。
四、分支、派生到本地、派生到新工作树，真正的区别在哪里
如果只用一句话概括三者的差异，可以这样理解：
Git 分支管理“历史指向”，派生到本地管理“当前目录里的直接修改”，派生到新工作树管理“独立的本地执行现场”。
这三者看起来都和“从当前状态继续做事”有关，但它们作用的位置根本不同。
| 维度 | Git 分支 | 派生到本地 | 派生到新工作树 |
|---|---|---|---|
| 核心对象 | 提交历史与引用 | 当前工作目录 | 新的独立检出目录 |
| 是否默认新建目录 | 否 | 否 | 是 |
| 是否直接影响当前项目现场 | 切换时会影响 | 会，且是直接影响 | 不会影响原目录 |
| 隔离强度 | 逻辑隔离 | 几乎无隔离 | 物理隔离 |
| 适合任务类型 | 常规版本管理 | 小改动、快速落地 | 并行任务、实验性改动、大规模 AI 修改 |
这张表里最重要的一行，不是“是否新建目录”，而是“隔离强度”。
很多开发者会下意识觉得：我已经建了分支，所以当然是隔离的。其实你隔离的只是提交线，不是你此刻眼前这份工作目录的运行现场。只要你还在同一个目录里工作，环境、缓存、未提交修改、编辑器状态，依然会彼此干扰。
而 Codex 正是把这种差异做成了显式选项：你是要让 AI 直接动你的当前现场，还是给它一个独立实验室？
五、为什么 AI 编程时代，worktree 的价值突然变大了
如果把时间倒回几年前，很多开发者其实几乎不会主动用 git worktree。不是它没用，而是大多数手工开发任务还没有频繁到非用不可。
但 AI 编程工具改变了一件事：单次修改的体量和不确定性都显著上升了。
过去你自己改代码，通常是一小步一小步推进；现在你让 Codex、CLI 或 IDE 代理去做，一个任务可能一次改十几个文件、跑多轮命令、顺手调整配置甚至修测试。效率确实更高，但风险也同步增加。
在这种背景下，Worktree 的价值就不再只是“高级 Git 技巧”，而是非常现实的工程隔离手段。
OpenAI 在 Codex app 的功能页和自动化文档中都把 Local 与 dedicated worktree 并列为运行模式：Local 会直接改你当前项目，Worktree 用于隔离尚未完成的本地工作，尤其适合并行任务和后台自动化。
这其实说明了一个趋势：AI 代理的默认工作单元，正在从“一次小补丁”转向“一次独立任务”。
而独立任务最自然的载体，恰恰不是“同目录里再切个分支”，而是“单独给它一个隔离现场”。
六、什么时候选“派生到本地”，什么时候选“派生到新工作树”
真正有用的，不是知道定义，而是知道什么时候选哪个。
1. 这些情况，优先选“派生到本地”
当你面对的是低风险、强上下文依赖、需要快速落地的任务时，Local 通常更高效。
比如：
- 修一个已经定位清楚的小 bug；
- 补几行类型声明或测试；
- 修改注释、文档、文案、配置项；
- 你已经在目标分支上，而且就是希望 Codex 直接帮你继续当前工作。
这时候再开一个 worktree，往往会增加不必要的切换成本。你真正需要的是速度，而不是隔离。
2. 这些情况，优先选“派生到新工作树”
当任务带有明显的试验性、并行性或大改动属性时，Worktree 基本上都是更稳妥的选择。
比如：
- 你想让 Codex 试做一个重构，但不确定结果值不值得保留；
- 你要同时推进两个方向相冲突的方案；
- 当前目录里已经有未提交工作，不想被 AI 混进去；
- 任务会运行安装、构建、迁移、批量改文件等高扰动操作；
- 你需要多个 Codex 任务并行工作在同一个项目上。
这类场景里，Worktree 的核心收益不是“方便”，而是降低认知负担和回滚成本。你不用时时刻刻盯着“别把主目录弄脏”，因为那个实验本来就发生在另一个目录里。
3. 那 Git 分支什么时候仍然是主角？
答案是：几乎一直都是。
因为无论你选择 Local 还是 Worktree，最终进入团队协作、代码评审、合并发布流程时，承载这些工作的仍然是分支与提交历史。Worktree 不是 branch 的替代品，它更像是 branch 在本地磁盘上的并行承载方式。
所以更准确的理解应该是：
分支负责把改动纳入版本管理，worktree 负责把改动放进独立现场；而“派生到本地”则是选择不创建这个独立现场，直接在你手上的现场里做事。
七、一个更实用的判断标准：看“你要不要保护当前现场”
很多时候，真正帮助你做决策的，不是去背定义，而是问自己一句话：
我现在最需要的，是立刻把修改落进当前项目，还是先保护手头这个现场不被打扰？
如果答案是前者，用“派生到本地”。如果答案是后者，用“派生到新工作树”。
这个判断标准之所以有效，是因为它抓住了 AI 编程时代最常见的矛盾：我们既想要代理帮我们大幅提速，又不想让高不确定性的改动干扰当前正在推进的正式工作。Local 解决的是“快”，Worktree 解决的是“稳”。
一旦把这件事想明白，你就不会再把这两个按钮误解成“只是有没有建分支”。因为它们真正控制的，是你如何组织自己的开发现场。
结语
Codex 的“派生到本地”和“派生到新工作树”，表面看只是两个执行选项，背后其实对应着两种完全不同的开发哲学。
前者强调的是直接介入当前上下文，适合快速、明确、低风险的改动；后者强调的是给任务一个隔离空间，适合实验、并行和高扰动任务。至于 Git 分支，它始终是版本管理的基础设施，但它本身并不会自动给你一个新的本地开发现场。
所以，真正准确的结论不是“这两个选项和建分支有什么区别”，而是：
分支解决的是版本线问题，worktree 解决的是工作现场问题；而 Codex 的两个选项，正是在让你选择“AI 该进入哪个现场工作”。
把这一点想清楚，你不只是更懂 Codex，也会更懂 Git 在 AI 编程时代为什么会出现新的最佳实践。
评论