AI Agent / 系统课时
使用 Git 工作树
使用 Git 工作树
并行运行多个 Codex 任务时,如果所有任务都写同一个工作目录,文件会互相覆盖,当前分支也会频繁被切换。Git worktree 为每个任务提供独立检出目录,让后台任务继续修改自己的文件,同时保留你的 Local 工作区不被打断。
学习目标
- 理解 Local、Worktree 与共享 Git 元数据之间的关系
- 能在 Codex 中从指定分支启动工作树并验证隔离状态
- 能通过 Handoff、分支规则和环境文件管理安全收回并行任务
工作树隔离的是工作目录
Git worktree 可以把同一个仓库检出到多个目录。每个 worktree 都有自己的一套工作文件,因此两个 Codex 聊天可以同时编辑同名文件而不会在磁盘上直接覆盖;这些检出目录仍共享同一仓库的提交、分支等 Git 元数据,所以最终合并时仍然可能发生语义冲突或文本冲突。
Codex 的托管 worktree 通常与单个聊天关联。创建聊天时选择 Worktree,Codex 会基于你指定的起始分支创建独立检出;默认使用 detached HEAD,避免为了每个后台任务都提前创建分支。Local 可以继续作为前台工作区,需要时再通过 Handoff 把聊天和代码移动回来。

在 Codex 中启动并验证工作树
项目必须位于 Git 仓库中。新建聊天时,在输入框下方选择 Worktree,再选择起始分支;它可以是 main、功能分支,或包含本地未提交修改的当前分支。提交任务后,Codex 创建托管 worktree。若起始分支带有本地修改,这些未提交修改也会被应用到新 worktree,因此想要“从干净 main 开始”时应先确认基线本身是干净的。
进入该聊天的集成终端后,可以用 Git 直接验证当前机器上的 worktree:
git worktree list
git status --short --branch预期输出
<LOCAL_PATH> <COMMIT> [main]
<WORKTREE_PATH> <COMMIT> (detached HEAD)
## HEAD (no branch)<LOCAL_PATH>、<WORKTREE_PATH> 与 <COMMIT> 会因机器和仓库而不同。看到第二个独立路径以及 detached HEAD,说明当前聊天确实没有直接占用 Local 的工作目录和分支。
让并行任务真正彼此独立
适合并行的任务通常可以在较长时间内独立推进,例如“修复支付重试逻辑”和“补齐日志字段”。分别为它们启动两个 worktree 后,每个聊天只修改自己的目录;你仍可在 Local 中处理第三件事。隔离减少的是 工作区互相踩文件,不是合并时的冲突,所以两个任务如果同时改了同一段业务逻辑,最终整合时仍要重新审查 diff 和测试。
新的 worktree 是新的 Git 检出,.gitignore 中的本地文件默认不会自动出现。若任务依赖 .env.local、本地配置或生成物,应优先用项目的环境初始化脚本准备依赖;对确实需要复制到 Codex 托管 worktree 的忽略文件,可以在仓库根目录维护 .worktreeinclude。不要把应受版本控制的源文件塞进这个列表,也不要用它绕过团队的密钥管理规则。
在 Worktree 与 Local 之间收回工作
当后台任务需要在你日常使用的 IDE、开发服务器或本地调试环境中继续验证时,使用聊天顶部的 Handoff 将它移动到 Local。Codex 会处理两个检出目录之间需要的 Git 操作;同一个聊天之后再移回 Worktree 时,会回到它原先关联的后台环境。
如果准备让任务长期留在 worktree 中,可以使用 Create branch here 为 detached HEAD 创建分支,再从该 worktree 提交、推送并发起 Pull Request。Git 规定同一个分支不能同时被两个 worktree 检出,因此不要在 worktree 已占用某分支时,又在 Local 强行切到同一分支。
把 Local 当作前台、Worktree 当作后台队列,会比频繁 stash、切分支和恢复现场更稳定:每个并行任务拥有自己的文件状态,真正需要人工检查时再通过 Handoff 或分支把成果带回主流程。