01-Worktree并行开发 - 从0开始的AI Coding 学习

你将完成什么

Git Worktree 允许同一仓库同时拥有多个工作目录。它适合让多个 Codex 任务并行开发，也适合在保留当前半成品的同时试验另一条方案。读完本页，你应该能够：

解释 worktree 共享什么、隔离什么；
创建、查看、锁定、移动、修复和删除工作树；
为并行任务分配独立分支、依赖、数据和端口；
让 Codex 在清晰边界内并行工作；
合并冲突、清理环境并在出错时回滚；
用可复现的证据完成安全验收。

命令以 macOS、Linux 和 Git Bash 为例。PowerShell 的环境变量写法另列。Git 或 Codex 版本有差异时，先运行 git worktree --help、codex --help 和具体子命令的帮助。

Worktree 只隔离 Git 工作文件和 Git 状态。.env、node_modules、构建缓存、数据库和端口不会自动隔离。

01 原理：它隔离了什么

工作树、分支和共享元数据

一个仓库可以有一棵主工作树和多棵附加工作树：

workspace/
├── billing/                         # main
├── billing-wt-feature-invoice/      # feat/INV-42
└── billing-wt-fix-timeout/          # fix/API-17

每个工作树有自己的：

工作文件；
HEAD 和索引；
未提交修改；
当前终端、开发服务器和调试进程。

它们共享同一套：

提交对象和历史；
本地分支与远程跟踪引用；
Git 配置和对象数据库；
worktree 注册信息。

所以 worktree 不是重新 clone，也不是远程仓库。创建它通常很快，但每个目录的依赖和构建输出仍可能独立占用磁盘。

它能解决什么，不能解决什么

适合并行的任务：

一个任务修 API，另一个开发不相关的前端页面；
一个任务重构，另一个只补测试或调查 CI；
保留稳定主线，同时在另一份目录进行可丢弃实验。

Worktree 不会自动解决：

两个任务修改同一文件后的逻辑冲突；
共享数据库、Redis、消息队列或第三方账号的相互污染；
开发服务器争用同一端口；
被 .gitignore 忽略的文件缺失；
锁文件或数据库迁移编号冲突。

它隔离的是目录和 Git 状态，不是整个运行环境。并行前必须同时规划文件、分支、依赖、数据、端口、进程和凭据。

同一分支只能在一处检出

一个本地分支同一时间只能在一个工作树中被检出。假设 feature/profile 已在另一个目录使用：

git -C ../project-main switch feature/profile

Git 会拒绝操作，并提示类似：

fatal: 'feature/profile' is already used by worktree at '.../project-feature'

这是保护机制，不要编辑 .git/worktrees 内部文件强行绕过。应当在原工作树继续工作，切换原工作树到其他分支，或完成任务交接。只查看某个提交可以用 detached HEAD：

git worktree add --detach ../project-review HEAD

这适合复现和检查，不适合作为长期开发分支。需要保留实验结果时创建新分支：

git switch -c experiment/profile-investigation

02 创建前检查

在仓库根目录执行，先确认路径、分支和工作区：

pwd
git rev-parse --show-toplevel
git status --short --branch
git branch --show-current
git worktree list --porcelain
git remote -v

确认：

当前目录是目标仓库，不是部署目录或相邻项目。
当前未提交修改已经提交、备份，或明确属于哪个任务。
目标基线是最新的，或者你知道它落后于远程多少。
新目录位于明确的父目录，不会被同步盘或清理工具误删。
任务不需要生产凭据、客户数据或不可恢复的外部操作。

只更新远程跟踪引用：

git fetch --prune origin
git log -1 --oneline main
git status --short --branch

fetch 不会覆盖工作文件。不要在有未提交修改时盲目 pull、reset 或清理。

03 命令：创建、查看和管理

创建已有分支

git worktree add ../project-profile feature/profile

从基线创建新分支

git worktree add -b feature/profile ../project-profile main

从远程基线创建：

git worktree add -b feature/profile ../project-profile origin/main

创建前先 git fetch origin，避免使用过期的本地基线。

查看工作树

人读的列表：

git worktree list

脚本和排障用：

git worktree list --porcelain

在指定工作树查看实际修改：

git -C ../project-profile status --short --branch
git -C ../project-profile log -3 --oneline --decorate

列表确认“注册关系”，status 才能确认“工作区是否干净”，两者不要混淆。

锁定、解锁和移动

移动磁盘、网络挂载或暂时离线的工作树可以锁定：

git worktree lock --reason "外接磁盘暂时离线" ../project-profile
git worktree unlock ../project-profile

锁定不会停止进程，也不是权限控制。移动目录时优先让 Git 更新登记：

git worktree move ../project-profile ../worktrees/project-profile
git worktree list

目录已经被外部工具移动时，确认新路径确实是原工作树后再修复：

git worktree repair ../worktrees/project-profile

删除和清理登记

删除干净的工作树：

git worktree remove ../project-profile

Git 拒绝删除含未提交修改的工作树。只有在保存差异并确认内容可以丢弃后才使用：

git worktree remove --force ../project-profile

如果目录已被外部删除，只清理失效登记：

git worktree prune --dry-run
git worktree prune

prune 不能恢复被删除的目录。先用 --dry-run 查看范围。

04 分支和提交边界

一个任务一条分支

git worktree add -b feat/INV-42 ../billing-wt-feature-invoice origin/main
git worktree add -b fix/API-17 ../billing-wt-fix-timeout origin/main

不要让两个 Codex 线程共享一个功能分支。每个任务独立提交、独立测试，才能明确责任、回滚和 PR 范围。提交前：

git -C ../billing-wt-feature-invoice diff --check
git -C ../billing-wt-feature-invoice diff --stat HEAD
git -C ../billing-wt-feature-invoice status --short --branch

使用路径精确暂存：

git -C ../billing-wt-feature-invoice add src/invoice tests/invoice
git -C ../billing-wt-feature-invoice commit -m "feat: add invoice page"

不要对边界不清的任务直接执行 git add .。提交后记录 SHA：

git -C ../billing-wt-feature-invoice log -1 --oneline --decorate

锁文件和迁移文件是共享冲突点

即使两个任务修改不同源文件，也可能同时修改：

package-lock.json、pnpm-lock.yaml、poetry.lock、go.sum；
导出索引和注册表；
数据库迁移编号；
CI、格式化配置和导航文件。

约束任务“不要升级无关依赖”。需要改依赖时，让一个任务负责生成锁文件，其他任务基于它的结果继续。数据库迁移编号必须在集成阶段重新检查。

05 依赖、配置和数据

新 worktree 缺少什么

Git 默认只检出已跟踪文件，以下内容通常不会出现：

node_modules、.venv、vendor；
.env、.env.local 和本地密钥；
dist、.next、coverage；
SQLite、上传目录、本地缓存；
IDE 私有设置和未跟踪脚本。

不要整目录复制主工作树的依赖和配置。原生依赖可能与分支不匹配，真实密钥也可能被带入错误任务。

可重复初始化

优先使用项目已有的 setup 脚本或 Codex local environment setup。示例：

#!/usr/bin/env bash
set -euo pipefail
corepack enable
pnpm install --frozen-lockfile
pnpm run typecheck

setup 应满足：

使用锁文件安装；
可重复执行；
不打印令牌；
不连接生产服务；
任一步失败立即退出。

安全生成本地配置：

cp .env.example .env.local

真实凭据使用操作系统凭据管理器、临时环境变量或最小权限测试账号。不要让 Codex 读取不需要的密钥，也不要把 .env 放入补丁和日志。

容器和数据库

为每个工作树使用独立 Compose 项目和数据卷：

docker compose -p billing-inv42 up -d db
docker compose -p billing-inv42 down

不要执行不带项目名的全局 docker compose down，它可能停止其他工作树的服务。测试数据库、schema、Redis 和消息主题都应有任务级命名。

06 端口和进程隔离

预先分配端口

端口表示例：

任务	Web	API	数据库
main	3000	8000	billing_dev
INV-42	3011	8011	billing_inv42_test
API-17	3012	8012	billing_api17_test

启动时显式传入：

WEB_PORT=3011 API_PORT=8011 pnpm dev

PowerShell：

$env:WEB_PORT="3011"; $env:API_PORT="8011"; pnpm dev

除了 Web 和 API，还要考虑 Vite、Storybook、调试器、数据库、Redis、队列和监控面板。端口应写进 Codex 任务说明。

启动前和启动后检查

macOS/Linux/Git Bash：

( command -v lsof >/dev/null && lsof -nP -iTCP:3011 -sTCP:LISTEN ) || true
curl -fsS http://127.0.0.1:8011/health

PowerShell：

Get-NetTCPConnection -LocalPort 3011 -State Listen -ErrorAction SilentlyContinue

发现占用时先查进程所属工作树，再换端口或有序停止。不要批量杀掉所有 Node、Python 或 Java 进程。记录 PID、工作目录和日志；验收后停止进程并确认端口释放。

07 Codex 并行任务

拆分原则

适合并行的任务具有清晰文件边界、低耦合和独立验收条件。不适合并行的任务包括：都修改同一个配置或锁文件、后者依赖前者尚未提交的接口、都迁移同一张表、都使用同一测试环境。有先后依赖时，先提交并验证前一个任务，再从它的分支创建后一个工作树。

CLI 工作流

Codex CLI 是否有内置 worktree 参数取决于版本，不要猜：

codex --help
codex exec --help

稳妥做法是先用 Git 创建，再从目标目录启动：

cd ../billing-wt-feature-invoice
codex

任务提示应包括目录、分支、允许文件、禁止事项、端口和验收命令：

你现在位于 ../billing-wt-feature-invoice，分支 feat/INV-42。
目标：实现发票列表页面，只修改 src/invoice、src/routes/invoice.tsx 和对应测试。
约束：不要修改数据库迁移、依赖锁文件或 .env；不要访问生产服务。
端口：前端 3011，API 8011。
完成标准：运行 pnpm test -- invoice 和 pnpm typecheck，报告 diff、测试输出和风险。
不要 commit、push 或 merge，除非我明确授权。

Desktop Worktree 模式

Codex Desktop 不同版本的入口和按钮名称可能变化，按当前界面为准。核心步骤是：

在 Git 仓库中新建线程并选择 Worktree。
选择起始分支或提交。
写明文件范围、依赖初始化、端口和验收命令。
运行后用 git worktree list 确认目录独立。
完成后查看 diff、测试和分支，再决定交接、提交或清理。

某些版本先创建 detached HEAD。要保留改动时，在确认归属后创建分支：

git switch -c feat/INV-42

Handoff 可以在 Local 与 Worktree 之间交接线程，但不会携带 .gitignore 文件。交接前后检查 .env、依赖、数据库和端口。

任务登记

工作树	分支	任务	Web/API	状态
`billing`	`main`	集成	3000/8000	稳定
`billing-wt-feature-invoice`	`feat/INV-42`	发票页面	3011/8011	开发中
`billing-wt-fix-timeout`	`fix/API-17`	超时修复	3012/8012	开发中
`billing-wt-test-contract`	detached 或检查分支	只读验证	无	检查

08 完整案例：两个任务并行到合并

1. 准备和创建

cd /work/billing
git fetch --prune origin
git status --short --branch
git worktree list --porcelain
git worktree add -b feat/INV-42 ../billing-wt-feature-invoice origin/main
git worktree add -b fix/API-17 ../billing-wt-fix-timeout origin/main
git worktree list

若主工作树有半成品，先保存证据：

git diff > /tmp/billing-main.patch
git diff --staged > /tmp/billing-main-staged.patch
git ls-files --others --exclude-standard > /tmp/billing-untracked.txt

2. 初始化和启动

cd ../billing-wt-feature-invoice
pnpm install --frozen-lockfile
cp .env.example .env.local

cd ../billing-wt-fix-timeout
pnpm install --frozen-lockfile
cp .env.example .env.local

分别使用 3011/8011 和 3012/8012，并使用不同测试数据库。启动两个 Codex 会话后，给它们互不重叠的文件范围：

INV-42：只修改发票页面和测试；运行 pnpm test -- invoice、pnpm typecheck。
API-17：只修改 API 客户端、超时处理和测试；运行 pnpm test -- api、pnpm typecheck。

两边都要求先列计划、展示 diff、不要自动提交或推送。发现它要求修改范围外的文件时先暂停。

3. 独立验收和提交

cd ../billing-wt-feature-invoice
git status --short --branch
git diff --check
git diff --stat
pnpm test -- invoice
pnpm typecheck
git add src/invoice src/routes/invoice.tsx tests/invoice
git commit -m "feat: add invoice list page"

cd ../billing-wt-fix-timeout
git status --short --branch
git diff --check
git diff --stat
pnpm test -- api
pnpm typecheck
git add src/api/client.ts src/api/timeout.ts tests/api
git commit -m "fix: handle API request timeout"

提交后记录：

git log -1 --oneline --decorate

4. 集成和总验收

在主工作树：

cd /work/billing
git status --short --branch
git switch main
git pull --ff-only origin main
git merge --no-ff feat/INV-42
git merge --no-ff fix/API-17
pnpm install --frozen-lockfile
pnpm test
pnpm typecheck
pnpm build

如果采用 PR，则分别推送分支，在 GitHub 审查后合并。不要使用 git push --force。即使两个分支各自通过，合并后也必须重新执行集成验收。

09 合并冲突

识别和保存现场

冲突常发生于路由、导出索引、锁文件、迁移、CI 和导航。开始合并后：

git status
git diff --name-only --diff-filter=U
git diff > /tmp/merge-conflict.patch

不要让 Codex 在不知道基线和意图时直接“解决全部冲突”。

标准流程

git switch main
git merge --no-ff feat/INV-42

逐个理解 <<<<<<<、=======、>>>>>>> 两边行为，结合测试和需求编辑。完成后：

git add path/to/resolved-file
git diff --cached --check
git diff --cached
# 确认后提交
 git commit

无法安全解决时：

git merge --abort

检查残留冲突标记：

rg -n '^(<<<<<<<|=======|>>>>>>>)' .
git diff --check

让 Codex 协助分析

先只读分析：

当前把 feat/INV-42 合并到 main。请只读取冲突文件和相关测试，说明两边行为、回归风险和推荐方案。
不要编辑、提交、推送或访问外部系统。等我确认方案后再修改。

授权后仍要人工查看完整 diff 和测试结果。

10 清理、归档和恢复

删除前清单

确认以下事项后再删除：

分支已合并，或明确放弃；
status、工作差异和未跟踪文件已经检查；
服务、容器、调试器和后台 Codex 已停止；
测试数据库和临时数据已清理；
SHA、日志和测试报告已保存；
备份中没有真实密钥和客户数据。

检查并删除：

git -C ../billing-wt-feature-invoice status --short --branch
git -C ../billing-wt-feature-invoice log -5 --oneline --decorate
git worktree list --porcelain
docker compose -p billing-inv42 down
git worktree remove ../billing-wt-feature-invoice
git branch -d feat/INV-42
git worktree prune --dry-run

未合并分支会被 git branch -d 拒绝。只有确认任务放弃并保存必要证据后才考虑 git branch -D。删除工作树不等于删除远程分支，远程分支按 PR 和团队规则处理。

Codex Desktop 托管工作树

Desktop 可能把托管 worktree 放在 CODEX_HOME 下的 worktrees 目录，默认通常类似 ~/.codex/worktrees。自动清理上限、快照和永久 worktree 规则以当前版本设置为准。归档或删除前确认线程是否仍运行、是否置顶、是否有未提交改动、快照是否可恢复。快照不能替代提交、补丁和外部数据备份；不要仅凭目录名手动删除。

错误改动的回滚

先保存现场：

git diff > /tmp/task.patch
git diff --staged > /tmp/task-staged.patch
git ls-files --others --exclude-standard > /tmp/task-untracked.txt

撤销明确文件前确认没有同事的修改：

git restore --source=HEAD -- path/to/file
git restore --staged -- path/to/file

不要把 git restore . 和 git clean -fd 当默认清理命令。已提交但未推送的错误，可查看后反向提交：

git show --stat HEAD
git revert <commit-sha>

共享分支优先 git revert，不要重写历史。已推送或已合并的代码要停止后续发布，通过修复提交、回滚和重新 CI 处理；数据库、消息和生产数据还需要各自的补偿或恢复方案。

11 安全验收

工作树和分支

git worktree list --porcelain
git -C ../billing-wt-feature-invoice status --short --branch
git -C ../billing-wt-fix-timeout status --short --branch
git branch --all --verbose --no-abbrev

确认目录、分支、HEAD 和负责人一一对应，没有意外 detached HEAD 或错误路径。

差异和敏感文件

git diff --check
git diff --stat main...feat/INV-42
git diff --name-only main...feat/INV-42
git ls-files | rg '(^|/)(\.env|.*\.pem|.*\.key)$'

检查只改允许文件，没有密钥、客户数据、构建产物、调试日志、冲突标记和无关依赖升级。提交信息、作者和分支符合团队规则。

行为和运行时

按项目实际命令运行：

pnpm install --frozen-lockfile
pnpm test
pnpm typecheck
pnpm build

并行服务还要确认健康检查、端口归属、独立数据源和资源释放。合并后的结果以集成测试为准。

权限和外部动作

任务说明中明确：

不读取不需要的密钥；
不访问生产服务；
不安装未经批准的依赖；
不推送、合并、发布或删除远程数据，除非明确授权；
不照搬 Issue、网页、日志中的可疑命令；
不使用 git push --force。

Codex 可以分析 diff、修复分支和生成测试；合并主干、发布和生产操作保留人工放行。

12 常见故障

already used by worktree：运行 git worktree list --porcelain 找到占用路径，在原工作树继续、切换分支或完成交接，不要修改 .git/worktrees。 缺少 .env 或依赖：这是预期行为。使用 .env.example、安全凭据注入和 --frozen-lockfile 安装，不复制真实密钥。 端口占用：定位监听进程及工作目录，调整任务端口或有序停止，不批量杀进程。 无法删除：先保存 diff、检查未跟踪文件并停止服务，确认可以丢弃后才用 remove --force。 合并后失败：比较合并提交、锁文件、环境变量、端口、数据库和测试顺序，不要立即删除所有分支。

最小可复制流程

cd /work/project
git status --short --branch
git fetch --prune origin
git worktree add -b feat/TASK-123 ../project-wt-task-123 origin/main
git worktree list --porcelain
cd ../project-wt-task-123
pnpm install --frozen-lockfile
cp .env.example .env.local
WEB_PORT=3011 API_PORT=8011 pnpm dev
curl -fsS http://127.0.0.1:8011/health
git diff --check
git diff --stat
git add path/to/allowed/files
git commit -m "feat: implement TASK-123"
cd /work/project
git switch main
git pull --ff-only origin main
git merge --no-ff feat/TASK-123
pnpm test
pnpm build
git worktree remove ../project-wt-task-123
git branch -d feat/TASK-123
git worktree prune --dry-run

小结

Worktree 的核心是边界：一个任务一条分支，一个分支同一时间只在一处检出；文件可以隔离，数据库、凭据、端口和进程必须另行隔离；新目录使用锁文件和可重复 setup 初始化；Codex 任务要有明确范围、禁止事项和验收命令；每个任务独立验证，合并后再做完整验证；删除前保存证据并停止资源，回滚优先用补丁和 git revert；合并、发布、强推和生产操作保留人工确认。参考资料：参考/codex/25-worktrees.md、参考/codex/26-git-github.md、参考/codex/31-speed.md。

​你将完成什么

​01 原理：它隔离了什么

​工作树、分支和共享元数据

​它能解决什么，不能解决什么

​同一分支只能在一处检出

​02 创建前检查

​03 命令：创建、查看和管理

​创建已有分支

​从基线创建新分支

​查看工作树

​锁定、解锁和移动

​删除和清理登记

​04 分支和提交边界

​一个任务一条分支

​锁文件和迁移文件是共享冲突点

​05 依赖、配置和数据

​新 worktree 缺少什么

​可重复初始化

​容器和数据库

​06 端口和进程隔离

​预先分配端口

​启动前和启动后检查

​07 Codex 并行任务

​拆分原则

​CLI 工作流

​Desktop Worktree 模式

​任务登记

​08 完整案例：两个任务并行到合并

​1. 准备和创建

​2. 初始化和启动

​3. 独立验收和提交

​4. 集成和总验收

​09 合并冲突

​识别和保存现场

​标准流程

​让 Codex 协助分析

​10 清理、归档和恢复

​删除前清单

​Codex Desktop 托管工作树

​错误改动的回滚

​11 安全验收

​工作树和分支

​差异和敏感文件

​行为和运行时

​权限和外部动作

​12 常见故障

​最小可复制流程

​小结