Git Worktree 从零到多智能体实战

工藤孤独2026-09-01 9:59

Git Worktree 从零到多智能体实战

一份可以边读边操作的中文教程：从第一次创建 worktree，到同时使用 Codex、Claude Code、Cursor 并行开发。

更新日期：2026-08-31。AI 工具的界面和命令变化较快，文末列出了官方资料。

1. 学完后你能做到什么

你将能在同一个 Git 仓库中，同时打开多个互不干扰的工作目录：

  • 主目录继续运行和审查稳定代码；
  • Codex 在一个 worktree 开发登录功能；
  • Claude Code 在另一个 worktree 修复支付问题；
  • Cursor 在第三个 worktree 做 UI 重构；
  • 最后把三个成果通过 commit、merge、rebase、cherry-pick 或 PR 安全汇总。

这不是把仓库复制三遍。多个 worktree 共享对象数据库和引用，因此通常比多次 git clone 更省空间，也能立刻看到彼此创建的 commit。

2. 先理解三个概念

2.1 仓库、分支和 worktree

  • Git 仓库：保存提交历史、对象、分支和标签。
  • 分支 ：一个会移动的提交指针，例如 main、feat/auth。
  • worktree ：一个实际可编辑的工作目录，拥有独立的 HEAD、暂存区和文件状态。

一个普通 git clone 默认包含一个主 worktree。git worktree add 可以给同一仓库增加多个"链接 worktree"。

text 复制代码 
同一个 Git 仓库（共享 commits / refs / remotes）
├── my-app/                 main            ← 主 worktree
├── my-app-wt-auth/         feat/auth       ← Codex
├── my-app-wt-payment/      fix/payment     ← Claude Code
└── my-app-wt-ui/           refactor/ui     ← Cursor

每个目录独立：HEAD、index、已修改文件、未跟踪文件
全仓库共享：提交对象、分支引用、标签、remote、stash（注意）

2.2 最重要的限制：一个本地分支通常只能被一个 worktree 检出

如果 main 已在主目录中，下面的命令通常会失败：

bash 复制代码 
git worktree add ../my-app-wt-main main

Git 这样做是为了防止两个目录同时更新同一分支。正确做法是给每个任务一个独立分支：

bash 复制代码 
git worktree add -b feat/auth ../my-app-wt-auth main

2.3 worktree 和 clone 怎么选

需求 选择
同一台机器、同一仓库、多分支并行 worktree
每个 AI 任务需要独立文件目录 worktree
完全独立的 Git 配置、remote、对象库 clone
跨机器、容器或云端 clone 或平台提供的隔离环境
超大仓库，只处理少数目录 worktree + sparse-checkout，或 partial clone

3. 从零开始：创建你的第一个 worktree

3.1 准备 Git 仓库

已有仓库可跳过本节。以下示例使用 macOS/Linux shell；Windows PowerShell 的 Git 命令相同，只需调整路径写法。

bash 复制代码 
mkdir worktree-demo
cd worktree-demo
git init -b main
printf '# Worktree Demo\n' > README.md
git add README.md
git commit -m "chore: initialize repository"

确认状态：

bash 复制代码 
git status
git branch --show-current
git log --oneline --decorate -5

如果是团队项目，先同步远程基线：

bash 复制代码 
git fetch origin --prune
git switch main
git pull --ff-only

--ff-only 可以避免一次普通拉取意外制造 merge commit。

3.2 推荐的目录布局

不要把手动 worktree 建在主仓库内部。最简单的是创建在相邻目录：

text 复制代码 
projects/
├── my-app/             主 worktree
└── my-app-wt-auth/     链接 worktree

在主仓库中运行：

bash 复制代码 
git worktree add -b feat/auth ../my-app-wt-auth main

参数含义：

  • -b feat/auth：创建新分支；
  • ../my-app-wt-auth：新工作目录；
  • main：新分支的起点。

进入新 worktree：

bash 复制代码 
cd ../my-app-wt-auth
git status
git branch --show-current

现在修改并提交：

bash 复制代码 
printf '\nAuth work starts here.\n' >> README.md
git add README.md
git commit -m "feat: start authentication work"

回到主目录后，提交已经存在于共享仓库中，但 main 还没有包含它：

bash 复制代码 
cd ../my-app
git log --oneline --all --decorate --graph -10

3.3 列出所有 worktree

bash 复制代码 
git worktree list
git worktree list --verbose
git worktree list --porcelain

脚本应使用稳定的 --porcelain 格式；人工查看用默认格式即可。

4. 六种常用创建方式

4.1 从 main 创建新任务分支（最常用）

bash 复制代码 
git worktree add -b feat/search ../my-app-wt-search main

4.2 从最新远程主分支创建

bash 复制代码 
git fetch origin
git worktree add -b feat/search ../my-app-wt-search origin/main

这样不会依赖本地 main 是否最新。创建后可以设置上游：

bash 复制代码 
cd ../my-app-wt-search
git push -u origin feat/search

4.3 检出一个已经存在、但未被其他 worktree 占用的分支

bash 复制代码 
git worktree add ../my-app-wt-search feat/search

4.4 检出远程分支并建立本地跟踪分支

bash 复制代码 
git fetch origin
git worktree add --track -b fix/issue-123 ../my-app-wt-123 origin/fix/issue-123

4.5 创建一次性实验环境，不绑定分支

bash 复制代码 
git worktree add --detach ../my-app-wt-experiment main

适合跑测试、做 benchmark 或阅读历史版本。若实验值得保留，先创建分支再提交：

bash 复制代码 
git switch -c experiment/new-parser

4.6 查看某个旧版本

bash 复制代码 
git worktree add --detach ../my-app-wt-v1 v1.0.0

5. 一个完整的日常开发闭环

假设主仓库路径为 ~/projects/shop，要开发优惠券功能。

步骤 1：同步并创建 worktree

bash 复制代码 
cd ~/projects/shop
git fetch origin --prune
git worktree add -b feat/coupon ../shop-wt-coupon origin/main

步骤 2：初始化这个独立目录

bash 复制代码 
cd ../shop-wt-coupon
cp ../shop/.env.example .env
npm ci
npm test

每个 worktree 的文件是独立的，所以通常需要单独安装依赖、创建虚拟环境、复制本地配置和启动服务。不要随意共享会被写入的构建目录。

步骤 3：开发、验证、提交

bash 复制代码 
git status
npm test
git add src test
git diff --cached
git commit -m "feat: add coupon validation"
git push -u origin feat/coupon

步骤 4：合入主线

可走 GitHub/GitLab PR；本地演示如下：

bash 复制代码 
cd ~/projects/shop
git switch main
git pull --ff-only
git merge --no-ff feat/coupon
npm test
git push origin main

团队项目通常更推荐 PR + CI + review，而不是直接推送 main。

步骤 5：安全清理

先确认分支已合并、目录干净：

bash 复制代码 
git -C ../shop-wt-coupon status
git branch --merged main

再移除 worktree 和分支：

bash 复制代码 
git worktree remove ../shop-wt-coupon
git branch -d feat/coupon
git worktree prune --dry-run
git worktree prune

git worktree remove 不会自动替你删除所有分支；git branch -d 会拒绝删除未合并分支，是比 -D 更安全的默认选择。

6. 与 Codex 一起使用

Codex 的核心原则很简单：一个独立任务对应一个 worktree 和一个分支。

6.1 方式 A：手动创建，适用于 CLI、IDE 和可重复流程

bash 复制代码 
cd ~/projects/shop
git fetch origin
git worktree add -b codex/refactor-cart ../shop-wt-codex-cart origin/main
cd ../shop-wt-codex-cart
codex

给 Codex 的提示词示例：

text 复制代码 
你正在分支 codex/refactor-cart 的独立 git worktree 中。
请重构购物车价格计算：
1. 先阅读 AGENTS.md 和相关测试；
2. 不修改公开 API；
3. 增加边界条件测试；
4. 运行相关测试和 lint；
5. 最后报告修改文件、验证结果和仍有的风险。
不要 merge、push 或删除 worktree。

把"不要 merge、push 或删除 worktree"写清楚，可以让审查权保留在你手中。若你希望 Codex 完成提交或推送，就明确授权并限定分支。

6.2 方式 B：Codex 桌面端新建任务时选择 worktree

在 Codex 中针对已保存的 Git 项目创建新任务时，可让任务运行在独立 worktree；主 checkout 保持不动。适合同时派发多个任务。任务完成后，在它自己的 diff/review 中检查，再提交或合入。

实用规则：

  • 新功能、修复、实验默认使用 worktree；
  • 只读分析可直接在当前 checkout；
  • 需要依赖本地未提交修改时，明确以当前 working tree 为起点；
  • 同一个分支不要再分配给另一个 worktree；
  • 任务已经在主 checkout 中启动但希望隔离时，可使用 Codex 的 handoff 功能在 checkout 与 worktree 之间移动任务及其 Git 状态。

6.3 Codex 并行示例

bash 复制代码 
git fetch origin
git worktree add -b codex/auth ../shop-wt-codex-auth origin/main
git worktree add -b codex/tests ../shop-wt-codex-tests origin/main
git worktree add -b codex/docs ../shop-wt-codex-docs origin/main

三个任务最好按职责切开：

Worktree 任务 尽量独占的文件范围
codex/auth 实现认证 src/auth/**
codex/tests 补集成测试 tests/integration/**
codex/docs 更新文档 docs/**

即使目录隔离，最后合并时仍可能冲突。按文件所有权拆任务，比"让三个 agent 都随意改全仓库"稳定得多。

7. 与 Claude Code 一起使用

Claude Code 当前提供原生 --worktree / -w。

7.1 原生创建

先在仓库中普通运行一次 claude，完成 workspace trust。然后：

bash 复制代码 
cd ~/projects/shop
claude --worktree feature-auth

默认会创建类似：

text 复制代码 
shop/.claude/worktrees/feature-auth/
branch: worktree-feature-auth

并行启动第二个会话：

bash 复制代码 
claude -w bugfix-payment

不提供名字时会自动生成。Claude Code 默认从远程默认分支 origin/HEAD 创建干净基线；若无法使用远程则回退到当前本地 HEAD。如需继承当前本地提交状态，可在设置中使用：

json 复制代码 
{
  "worktree": {
    "baseRef": "head"
  }
}

7.2 复制 .env 等被忽略文件

新 worktree 不会自动拥有主目录中未跟踪、被忽略的文件。Claude Code 支持在仓库根目录创建 .worktreeinclude：

gitignore 复制代码 
.env
.env.local
config/secrets.local.json

只有"匹配规则且已被 Git 忽略"的文件才会复制；不要把生产密钥纳入仓库。

同时把 Claude 管理目录加入 .gitignore：

gitignore 复制代码 
.claude/worktrees/

7.3 手动 worktree + Claude Code

想完全控制分支名和目录时：

bash 复制代码 
git worktree add -b claude/payment ../shop-wt-claude-payment origin/main
cd ../shop-wt-claude-payment
claude

这也便于让 Cursor 或 Codex 稍后打开同一个目录进行审查。

7.4 子代理隔离

你可以要求 Claude "让每个会改代码的 subagent 使用独立 worktree"，或在自定义 subagent frontmatter 中设置：

yaml 复制代码 
isolation: worktree

适合并行处理互相独立的子任务。仍应限制每个 agent 的文件范围，并由主会话负责集成。

8. 与 Cursor 一起使用

Cursor 有三种常见做法。

8.1 最稳妥：手动创建后直接打开目录

bash 复制代码 
git worktree add -b cursor/ui ../shop-wt-cursor-ui origin/main
cursor ../shop-wt-cursor-ui

如果 cursor shell 命令未安装，在 Cursor 中选择 File → Open Folder，打开 worktree 目录即可。

给 Cursor Agent 的示例：

text 复制代码 
当前窗口是 refactor/ui 分支的独立 worktree。
只重构 components/checkout 下的 UI，不改后端接口。
先列计划，再修改；运行单测和类型检查；不要 merge 或删除 worktree。

8.2 Cursor IDE / Agents Window 的原生 worktree

当前 Cursor 文档说明：Agents Window 可以为任务创建独立 worktree；IDE 中可使用：

text 复制代码 
/worktree fix the failing auth tests and update the login copy

完成后可用 /apply-worktree 把结果带回当前 checkout，结束后用 /delete-worktree。执行前仍应检查 diff 和测试结果。

同一提示词尝试多个模型可使用 /best-of-n；每个候选在独立 worktree 中运行，挑选优胜方案后再应用或提交。

8.3 Cursor CLI

bash 复制代码 
agent --worktree "upgrade the test runner and fix broken snapshots"
agent --workspace ~/projects/shop --worktree auth-fix "fix the flaky auth test"

Cursor CLI 管理的 worktree 通常位于 ~/.cursor/worktrees/<repo>/<name>。平台管理的 worktree 可能受清理和保留策略影响；长期成果应及时 commit、push 或迁移到你明确管理的分支。

9. 三款 AI 工具一起协作：完整示例

目标：给商城增加登录功能、修复支付重试、改进结算页 UI。

9.1 建立三个隔离目录

bash 复制代码 
cd ~/projects/shop
git fetch origin --prune

git worktree add -b ai/codex-auth ../shop-wt-codex-auth origin/main
git worktree add -b ai/claude-payment ../shop-wt-claude-payment origin/main
git worktree add -b ai/cursor-checkout ../shop-wt-cursor-checkout origin/main

启动工具：

bash 复制代码 
cd ../shop-wt-codex-auth && codex
cd ../shop-wt-claude-payment && claude
cursor ../shop-wt-cursor-checkout

在三个终端分别运行前两条；第三条打开 Cursor 窗口。

9.2 给每个 agent 一张清晰的任务卡

每张任务卡至少包含：

text 复制代码 
目标：一句话定义完成状态。
范围：允许修改的目录和接口。
禁止：不能改的 API、配置、数据库结构等。
验证：必须运行的测试、lint、类型检查或构建。
交付：提交与否、是否允许 push、最终报告内容。
依赖：基于哪个 commit；是否依赖其他任务。

示例分配：

  • Codex：实现 src/auth/**，补 tests/auth/**，禁止改支付和结算 UI；
  • Claude Code：修复 src/payment/retry.ts，增加故障注入测试；
  • Cursor：只改 src/components/checkout/** 和对应视觉测试。

9.3 集成顺序

若任务互不依赖，可分别开 PR。若必须本地整合，建议建专门的集成分支和 worktree：

bash 复制代码 
cd ~/projects/shop
git worktree add -b integrate/ai-batch ../shop-wt-integrate origin/main
cd ../shop-wt-integrate

git merge --no-ff ai/codex-auth
git merge --no-ff ai/claude-payment
git merge --no-ff ai/cursor-checkout
npm test
npm run lint
npm run build

如果只要某个 agent 的少数提交：

bash 复制代码 
git cherry-pick <commit-sha>

如果希望每个分支在最新主线之上先自行解决冲突：

bash 复制代码 
cd ../shop-wt-codex-auth
git fetch origin
git rebase origin/main

不要让多个 agent 同时 rebase、merge 或修改同一个集成分支。

10. 依赖、端口和环境变量隔离

10.1 Node.js

每个 worktree 默认需要自己的 node_modules：

bash 复制代码 
npm ci

可以利用 npm/pnpm 的全局内容缓存减少磁盘开销，但不要简单让多个 worktree 共享一个可写 node_modules，否则安装和生成文件可能互相影响。

10.2 Python

每个 worktree 创建独立虚拟环境：

bash 复制代码 
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

10.3 服务端口

并行运行时要分配不同端口：

text 复制代码 
主目录             3000 / 5432
Codex worktree      3011 / 5441
Claude worktree     3012 / 5442
Cursor worktree     3013 / 5443

可在每个 worktree 的 .env.local 中配置，且确保该文件已被忽略。

10.4 数据库

不要让三个 agent 的破坏性测试指向同一个开发数据库。可使用：

  • 每个 worktree 独立的数据库名；
  • 独立 Docker Compose project name；
  • 每个测试运行创建临时数据库；
  • 只读共享数据 + 独立写入层。

11. 高频问题与修复

11.1 fatal: 'branch' is already checked out at ...

原因：该分支已被另一个 worktree 使用。

bash 复制代码 
git worktree list

选择：进入现有目录；新建另一个分支；或在安全移除旧 worktree 后再检出。不要用 -f 掩盖没弄清的分支占用。

11.2 手动删除了 worktree 目录

清理残留元数据：

bash 复制代码 
git worktree prune --dry-run
git worktree prune --verbose

下次优先使用 git worktree remove <path>。

11.3 手动移动目录后失联

优先：

bash 复制代码 
git worktree move <old-path> <new-path>

已经手动移动可尝试：

bash 复制代码 
git worktree repair <new-path>

11.4 worktree 有未提交修改，无法删除

先检查：

bash 复制代码 
git -C ../shop-wt-auth status --short
git -C ../shop-wt-auth diff
git -C ../shop-wt-auth diff --cached

选择提交、stash 或备份后再移除。git worktree remove --force 会造成未提交内容丢失，只在你明确确认可丢弃时使用。

11.5 .env、依赖或生成文件不见了

这是新 worktree 的正常表现：未跟踪文件不会随 checkout 出现。使用模板、初始化脚本或工具提供的 include/setup 机制，不要把秘密提交进 Git。

11.6 锁定长期离线的 worktree

外置硬盘或网络盘暂时不可用时：

bash 复制代码 
git worktree lock --reason "external SSD used for benchmark" ../shop-wt-bench
git worktree unlock ../shop-wt-bench

锁定可防止元数据被 prune。

11.7 stash 是否隔离

不要把 stash 当作每个 worktree 的私有抽屉；stash refs 属于共享仓库。命名清楚：

bash 复制代码 
git stash push -u -m "ai/codex-auth before rebase"
git stash list

更稳妥的长期交接方式仍是小粒度 commit。

11.8 子模块

Git 官方文档仍提示多 worktree 对含 submodule 的 superproject 支持不完整。使用前应在你的 Git 版本和项目上验证；对关键任务可考虑单独 clone。

12. 最佳实践清单

创建前

  • git fetch origin --prune；
  • 明确基线是本地 HEAD 还是 origin/main；
  • 一个任务一个分支；
  • 目录名、分支名和 agent 名保持可对应；
  • 先约定文件所有权和合并顺序。

Agent 工作时

  • 提示词写明范围、禁区、验证和 Git 权限；
  • 不让多个 agent 修改同一分支；
  • 不让多个 agent 同时操作共享数据库或相同端口；
  • 频繁做小而清晰的 commit；
  • 不让 agent 擅自删除 worktree；
  • 长任务及时 push，避免自动管理目录被清理。

集成前

  • 查看 git status、git diff 和提交历史；
  • 运行目标测试，再运行集成测试；
  • 检查依赖锁文件、migration、生成代码和 API 变更；
  • 让一个明确的"集成负责人"处理合并；
  • 不只相信 agent 的总结，要审查实际 diff。

清理前

  • 确认需要的 commit 已合并或 push；
  • 使用 git worktree remove，不要直接删目录；
  • 使用 git branch -d，谨慎使用 -D；
  • 先 git worktree prune --dry-run 再真正 prune。

13. 可直接复制的命令速查表

bash 复制代码 
# 列出
git worktree list
git worktree list --verbose

# 从远程主线创建新分支 + worktree
git fetch origin --prune
git worktree add -b feat/my-task ../repo-wt-my-task origin/main

# 已有分支
git worktree add ../repo-wt-my-task feat/my-task

# 临时 detached worktree
git worktree add --detach ../repo-wt-test origin/main

# 移动 / 锁定 / 修复
git worktree move ../old ../new
git worktree lock --reason "long-running task" ../new
git worktree unlock ../new
git worktree repair ../new

# 安全移除
git -C ../repo-wt-my-task status
git worktree remove ../repo-wt-my-task
git branch -d feat/my-task

# 清理失效记录
git worktree prune --dry-run
git worktree prune --verbose

三款工具：

bash 复制代码 
# 手动 worktree 中启动 Codex
cd ../repo-wt-codex && codex

# Claude Code 原生 worktree
claude --worktree feature-auth

# 手动 worktree 中启动 Claude Code
cd ../repo-wt-claude && claude

# Cursor 打开手动 worktree
cursor ../repo-wt-cursor

# Cursor CLI 原生 worktree
agent --worktree my-task "implement the task and run tests"

14. 推荐的一套团队规范

text 复制代码 
分支：ai/<tool>/<ticket>-<slug>
目录：../<repo>-wt-<tool>-<ticket>
提交：小粒度、可独立回滚
权限：默认可修改和测试；默认不可 merge、push、删 worktree
集成：PR 优先；一个人或一个专门 agent 负责合并
清理：合并后 remove worktree，再 branch -d

例如：

bash 复制代码 
git worktree add \
  -b ai/codex/123-auth-refresh \
  ../shop-wt-codex-123 \
  origin/main

15. 最后一个心智模型

把 worktree 当成"共享 Git 历史、隔离文件现场的任务房间"：

  • 分支决定成果属于哪条提交线；
  • worktree 决定谁在哪个独立目录工作；
  • agent 是房间里的执行者；
  • commit 是可靠的交接单；
  • PR 或集成分支是总装线。

只要坚持"一个任务、一个分支、一个 worktree、一个明确负责人"，Codex、Claude Code 和 Cursor 就能并行工作，而不是互相覆盖文件。

官方资料

相关推荐
微尘寒风10 小时前
【Git】的安装和使用
java·git
胖大和尚20 小时前
Git初始化本地文件夹，并推送到远端
git
啵啵啵123420 小时前
Git 底层原理：分支为什么只是一个 41 字节的文件
git
demon75520031 天前
Git Worktree详解介绍
git·worktree
胖大和尚1 天前
当前仓库推送到同一台机器上的另一个文件夹
git
轮到我狗叫了2 天前
git - 版本控制工具 - 对应的常见命令 - 以及无需后续每次手动source conda
git
changxiang2 天前
GIT 备忘
git
DogDaoDao2 天前
Windows 开发提效工具全景指南：60+ 工具的工程化分层配置
windows·git·程序员·开发工具·powershell·everything·msys2
wdfk_prog3 天前
GitHub push 失败：如何扫描并清理 Git 历史中的大文件
git·elasticsearch·github
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02GitHub 镜像站点03ZCode 周末送额度活动开启：3 亿 Token 免费领取04历年考研数学一、数学二、数学三真题试卷及答案PDF052026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？06蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接07微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新08AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路09Agnes AI 免费 API 接入指南：文本、生图、生视频，一套接口全免费10VSCode+CodeX扩展，无法启动