Git Worktree：从热修到 Agent 并行

你正在重构登录页，二十多个文件已经改到一半，测试还没恢复。线上突然传来消息：支付按钮坏了，需要马上修。

如果只有一个项目目录，你大概会先停下重构，检查有没有漏掉的未跟踪文件，再 stash、切到 main、拉出热修分支。修完以后，还要按相反顺序把刚才的现场拼回来。另一种办法是重新 clone 一份仓库，但下载、配置和目录管理又显得很重。

Git worktree 提供了第三条路：保留眼前这个凌乱却完整的现场，在旁边再摆一张干净的工作台。

git worktree add -b hotfix/payment ../shop-hotfix main

运行以后，../shop-hotfix 是一个新的目录，里面检出了从 main 出发的 hotfix/payment 分支。原来的登录页改动没有被收起，也没有被覆盖。你可以打开第二个编辑器窗口去修支付问题，结束后再回到原目录，屏幕上的文件仍停在离开时的样子。

Git 在 2015 年发布的 2.5 版本中加入了内置的 worktree 功能，让这张额外的工作台成为 Git 正式管理的一部分。它最初解决的是中途插入热修、同时检出多个分支等问题。十多年后，当同时工作的不再只是“你上午的任务”和“下午插进来的热修”，而是三四个会自主改文件、跑测试、提交代码的 Coding Agent，这张额外的工作台突然从小众技巧变成了并行开发的基础设施。

一、仓库、分支与工作树

Worktree 直译是“工作树”。这个名字容易让人以为它是一种新的分支，或者仓库的完整副本。简单说，它就是一个检出了某个版本、可以直接编辑文件的项目目录。

平时使用的 Git 仓库里，已经有一棵工作树：就是你能在编辑器里看到的源代码、图片和配置文件所在的目录。git clone 或 git init 创建的这棵，官方称为 main worktree，也就是主工作树。通过 git worktree add 增加的目录叫 linked worktree，也就是关联工作树。

下面的图会展示多个工作树之间哪些数据共享、哪些状态各自独立。点击不同目录查看。

这里有三个容易混在一起的概念：

• Repository，仓库：保存提交对象、分支引用和版本历史的共同档案室。
• Branch，分支：一个会随提交向前移动的名字，例如 main 或 feature/login。它指向历史中的某个提交，不是一份独立文件夹。
• Worktree，工作树：一个真实目录，里面有某个提交展开后的文件，以及这个目录自己的当前分支、HEAD 和暂存区。

登录页改到一半，支付按钮突然坏了。你有两种做法：

• 只建分支：Git 记下另一条开发线，但还是同一个项目目录。切过去修支付前，可能得先收好登录页的未提交改动。
• 建 worktree：Git 另外创建一个项目目录。登录页留在原处，支付问题在新目录里修。

git worktree add -b hotfix/payment ../shop-hotfix main

这条命令会创建 shop-hotfix/，并在里面切到 hotfix/payment 分支。记住这点就够了：分支是开发线，worktree 是可以同时打开的另一个项目目录。

共享与独立同时存在

多个 worktree 共享同一个对象库和大部分 refs。你在 shop-hotfix/ 中提交一次，新的 commit 对象和 hotfix/payment 分支移动会立刻进入共同仓库；回到 shop/ 运行 git log --all，已经可以看到它。

但每棵 worktree 都有自己的：

• 工作目录中的文件状态；
• HEAD，也就是当前查看的位置；
• index，也就是通常所说的暂存区；
• 一部分正在进行的操作状态，例如 rebase 或 bisect。

为什么未提交的修改不会互相覆盖？ 因为 shop/ 和 shop-hotfix/ 是硬盘上的两个目录。登录页的未提交文件还在 shop/ 里；支付修复发生在 shop-hotfix/ 里。改一个目录的文件，不会直接改到另一个目录。等你提交后，提交记录才会进入两边共用的仓库历史。

为什么不能让两个目录检出同一个分支？ hotfix/payment 这个分支名只有一个。假设两个目录都检出它：你在 shop-hotfix/ 提交后，这个分支名就指向新提交；但另一个目录里的文件还停在旧版本。接下来在那里继续改、提交，很容易让人弄不清改动是从哪个版本开始的。Git 因此规定：一个本地分支同一时间只能在一个 worktree 中检出。两个目录要同时工作，就各用自己的分支名。

记住这个区别：未提交的文件改动留在各自目录；提交记录由仓库共享；每个 worktree 同时只能检出自己的分支。

二、Worktree 的由来

Worktree 不是为了 AI 发明的。它来自一个很早就存在的开发矛盾：Git 的分支很轻，但硬盘上的工作目录一次只能呈现一个检出状态。

早期用户已经会用 GIT_DIR、GIT_WORK_TREE 或手工符号链接，把同一仓库的元数据连接到多个目录。Git 源码也曾附带一个位于 contrib/workdir/ 的辅助脚本 git-new-workdir。contrib 可以理解为随项目提供、但没有完全成为核心命令的一组贡献工具。这个脚本能共享对象和 refs，却依赖符号链接，仓库本身也不充分了解还有哪些工作目录正在借用它，安全边界比较脆弱。

2015 年发布的 Git 2.5 加入了替代方案。发布说明没有把它描述成凭空出现的新创意，而是明确说：它用于替代 git-new-workdir，不再依赖符号链接，并让共享关系中的双方都知道彼此存在。这个版本当时仍把多工作树标为实验性功能，界面也可能继续变化。

最初的 Git 2.5 worktree 文档 只有少量核心能力：add 用来增加工作树，prune 用来清理失效的管理记录。随后 Git 逐步补齐了生命周期管理：可以列出、锁定、移动、删除、修复 worktree，也加入了更稳妥的脚本输出和每棵工作树独立配置等能力。

这段历史里最重要的不是记住版本号，而是看清它的演化方向：

1. 用户先用脚本解决“同一历史、多个目录”的真实需求。
2. Git 把隐蔽的符号链接关系变成仓库明确管理的关联关系。
3. 功能从“能再检出一份”发展为完整的创建、检查、移动、修复与清理流程。

Git 官方文档至今仍以一个突发热修作为典型例子：重构现场很乱，不想冒险 stash，就新建一棵临时 worktree 修复紧急问题。也就是说，worktree 的原生使命不是制造更多分支，而是让已经很轻的分支能够同时出现在不同目录里。

三、Worktree、stash 与 clone

这四种做法都可能让你“处理另一项工作”，但代价分布完全不同。

Worktree 比重复 clone 轻，主要不是因为源代码文件消失了。每个 worktree 仍要在硬盘上展开一份被检出的文件；大型依赖目录也可能需要分别安装。省下的是重复的 Git 对象库，例如相同的 commit、tree 和 blob，以及重新 clone 和同步历史的成本。

它也不等同于 stash。Stash 像把桌面物品装进一个有标签的箱子，再清空原桌面；worktree 则是保留原桌面，直接打开第二张桌子。前者仍然是串行切换，后者允许两个现场同时存在。

Worktree 不是容器

文件目录隔离很容易让人产生过度联想。Worktree 不是 Docker 容器、虚拟机或权限沙箱。多个 worktree 仍可能共享：

• 同一台机器的端口，例如都想监听 3000；
• 同一个开发数据库、缓存或云端测试环境；
• 用户目录里的全局配置、凭据和工具缓存；
• 仓库级 Git 配置与 hooks；
• 被代码写到 worktree 之外的文件。

所以 worktree 隔离的是仓库内的文件现场和 Git 操作状态，不是进程能接触到的一切资源。这条边界到了 Agent 并行阶段尤其重要。

四、安全工作流

多数日常使用不需要记很多参数。沿着“查看、创建、工作、汇合、清理”走一遍，已经覆盖了最常见的热修与并行任务。

git worktree list

shop/ → main

git worktree add -b hotfix/payment ../shop-hotfix main

shop/ → main
shop-hotfix/ → hotfix/payment

cd ../shop-hotfix
# 修改、测试、提交

hotfix/payment → f031c4

git switch main
git merge hotfix/payment

main 包含支付修复

git worktree remove ../shop-hotfix
git branch -d hotfix/payment

只剩 shop/ → main

查看已有工作树

git worktree list

输出会列出路径、当前提交和分支。它应该成为创建和清理前的第一个动作，因为一个你想使用的分支可能已经在另一个目录中工作。

如果脚本需要稳定格式，可以使用：

git worktree list --porcelain

创建新分支与新目录

最清楚的写法是同时给出新分支、目录和起点：

git worktree add -b hotfix/payment ../shop-hotfix main

它做了三件事：从 main 创建 hotfix/payment，创建 ../shop-hotfix 目录，再把新分支检出到这个目录。

如果分支已经存在，可以直接检出：

git worktree add ../shop-login feature/login

只想临时运行旧版本测试，不打算推动某个分支时，可以创建 detached HEAD 的工作树：

git worktree add --detach ../shop-check v2.3.0

Detached HEAD 的中文直觉是“当前指向一个提交，而不是跟着某个分支名”。可以查看和试验；若产生了值得保留的提交，记得及时创建分支。

工作与汇合仍然使用普通 Git

进入新目录以后，修改、暂存、提交、推送都和平时一样：

cd ../shop-hotfix
npm test
git add src/payment.ts tests/payment.test.ts
git commit -m "fix: restore payment submission"

Worktree 没有发明新的合并方式。任务完成后，仍然通过 pull request、merge、rebase 或 cherry-pick 把结果带回目标分支。它改变的是工作发生在哪里，不是历史如何组合。

清理工作树

完成后运行：

git worktree remove ../shop-hotfix
git branch -d hotfix/payment

第一条删除关联工作目录，第二条按需删除已经合并的分支。Git 会拒绝直接移除含有未提交改动的 worktree，这是有意设置的保护。

若你已经手工删除了目录，仓库里可能留下失效记录。先预览，再清理：

git worktree prune --dry-run
git worktree prune

移动了主仓库或关联目录，导致连接失效时，优先使用 git worktree repair，不要手工猜测 .git/worktrees/ 中的内部文件。

一次可复述的路径是：先列清单，再从明确基线创建；独立完成并提交；用普通分支流程汇合；确认干净后由 Git 清理目录。

五、Agent 并行

人独自写代码时，常见节奏是一次专注一项工作。登录页没写完，支付热修只能插队。Worktree 能减少切换成本，但很多人并不经常需要两张同时活跃的工作台，因此它长期像一个“知道很好、偶尔才用”的工具。

Coding Agent 改变了瓶颈。生成和修改代码的执行者突然可以同时有多个：一个实现登录页，一个修支付问题，一个升级依赖。此时限制并行度的，不再只是人的手速，而是它们能不能同时写同一个仓库而不踩乱彼此的文件现场。

下面保持三个任务完全相同，只切换“共用一个目录”与“每个任务一棵 worktree”。

如果三个 Agent 共用一个目录，即使它们声称各自在不同分支上工作，进程看到的仍是同一组文件和同一个 index。A 切分支会改变 B 正在读取的文件；B 暂存文件可能把 C 的改动带进提交；一个 Agent 运行格式化，也可能重写另一个 Agent 正在编辑的文件。为了安全，它们只能排队，或者依赖非常脆弱的协作约定。

一任务一 worktree 后，每个 Agent 得到：

• 一个稳定的起始提交；
• 一个独立分支；
• 一套独立的源文件与暂存区；
• 可以单独检查、测试和丢弃的 diff。

这也是为什么当代 Agent 工具越来越常把 worktree 当成会话隔离单元。GitHub 在介绍并行 Agent 会话时，也明确把“每个会话位于自己的 worktree 和分支”作为文件、对话与任务状态隔离的基础； GitHub Desktop 的 worktree 支持 同样把 Agent 并行列为直接使用场景。

这里发生的不是 worktree 本质改变了，而是生产关系变了：以前它让一个人不必收拾上一张桌子；现在它让多个执行者同时拥有各自的桌子。

六、Vibe Coding 的审阅边界

Vibe coding 常把需求表达、实现选择和大量文件修改压缩进一次对话。速度上升后，新的成本会落在监督：哪一个 Agent 改了什么，它从哪里出发，结果能不能独立测试，不满意时能不能完整丢弃。

Worktree 在这里提供的价值不只是“更快”，还有一条清楚的责任边界：

当一次实验失败，你可以删除它的 worktree 和分支，而不用从混杂的主目录中辨认哪些文件属于谁。当两个 Agent 给出不同方案，你也可以分别启动应用、比较 diff 和测试结果，再选择其一。这让“让 Agent 试试看”从不可控的直接改写，变成一个有入口、有出口的实验单元。

任务命名

假设仓库是 shop，可以把 Agent 工作树集中放在相邻目录：

projects/
├── shop/                    # main，人负责汇合与最终验证
├── shop-wt-login/           # agent/login
├── shop-wt-payment/         # agent/payment-hotfix
└── shop-wt-deps/            # agent/deps-upgrade

分支和目录都带上短任务名，目的是让 git worktree list 的结果一眼可读。目录不必使用 wt，分支也不必使用 agent/；稳定一致比具体格式重要。

给 Agent 的任务边界至少可以包含：

只在当前 worktree 内修改。
从当前分支开始，不切换或重置其他分支。
不要改写 worktree 之外的文件。
完成后运行指定测试，提交变更，并总结风险与未完成项。
不要合并到 main；等待人工评审。

这些约束不是因为 worktree 不可靠，而是因为它只负责文件现场。Agent 是否选对方案、是否修改了外部服务、是否擅自扩大范围，仍要靠任务说明、权限和评审控制。

检查任务依赖

能创建三棵 worktree，不代表三项任务适合并行。可以先看它们可能触碰的边界：

Worktree 把执行冲突推迟成更容易看见的集成冲突，却不会让冲突凭空消失。这已经很有价值：文件不会在生成过程中互相覆盖，失败也局限在单个目录。但最终仍需有人决定多个正确的局部修改能否组成正确的系统。

七、并行工作的常见风险

起点过旧

Agent 从昨天的 main 建立 worktree，今天完成时主线已经前进很远。隔离没有问题，集成成本却被拖到最后。长任务应定期明确是否需要 fetch、rebase 或重新建立基线，更新前先确认工作区状态。

两个任务改同一片语义

Git 只能检测部分文本冲突。A 改了折扣计算，B 在另一个文件里改变了税费顺序，即使自动合并没有冲突，组合后的业务含义也可能错。这叫语义冲突，必须靠测试、评审和系统理解发现。

共享端口与数据库

多个 worktree 的开发服务器如果都绑定同一个固定端口（例如 3000），后启动的进程可能遇到端口占用；有些工具会自动改用其他端口，也容易让人打开错误的服务。更危险的是共用开发数据库：一个 Agent 迁移 schema，另一个的测试数据随之变化。为每项任务分配端口、数据库名称或临时环境，才是完整并行方案。

依赖占用大量空间

Git 对象库共享，不代表 node_modules、构建产物和缓存一定共享。多个大型 worktree 可能迅速占满磁盘。包管理器的全局内容寻址缓存可以减少下载，但每个项目目录仍可能产生链接、构建缓存和输出文件。

把关联目录放进仓库内部

若把 worktree 建在主目录的未忽略子目录里，主 worktree 可能把整个关联目录视为未跟踪内容。更稳妥的默认选择是相邻目录，例如 ../shop-wt-login；若团队采用仓库内部的统一目录，则必须先设计好忽略规则和工具兼容性。

清目录却忘了清记录

手工删除文件夹可能留下 prunable 记录；长时间保留的临时 worktree 又会让分支和目录清单越来越难读。把 git worktree list、remove 和 prune --dry-run 纳入日常收尾，比偶尔进行一次大扫除可靠。

此外，Git 当前官方文档仍提醒：多工作树与 submodule 的组合支持并不完整，不建议对包含 submodule 的超级项目随意做多个 checkout。遇到这类仓库，应先在小范围验证真实行为，而不是假设每个依赖都会自然隔离。完整命令与最新限制以 git-worktree 官方文档 为准。

八、从工作树到并行调度

现在回放整条路径。

最初的问题是：一个 Git 仓库的分支很轻，但一个工作目录只能呈现一个文件现场。人们先用额外脚本和符号链接连接多个目录；Git 2.5 把这件事变成仓库明确知道、能够管理的 linked worktree。它首先服务于很传统的场景：开发中途处理热修、同时测试另一个版本、保留一个长期构建目录。

Agent 时代没有改写这个机制，只把它的价值放大了：

共同仓库 → 为每项任务创建独立分支与 worktree → 多个 Agent 分别修改和测试 → 通过 diff、提交与测试评审 → 再把结果汇合到主线

这条链路里，worktree 做了两件很具体的事：让并行写文件成为可能，让每项变化可以单独审阅和丢弃。它没有替你拆分任务，没有判断代码对错，也没有隔离端口、数据库和云端资源。

因此，在 vibe coding 中使用 worktree，最稳妥的心态不是“终于可以无限开 Agent”，而是：

给每个并行实验一张独立工作台、一个明确起点和一条独立分支；完成后再把人的注意力放在差异、验证与汇合上。

Worktree 出生时解决的是“不要为了一个热修毁掉手头现场”。到了 Agent 时代，它承担的是同一个更大版本的问题：不要让更多执行者共享一个混乱现场。

延伸阅读

• Git 2.5 Release Notes ：worktree 正式进入 Git 时的发布说明。
• git-worktree 官方文档 ：当前命令、配置、内部结构与限制。
• Git repository layout ：理解 $GIT_DIR/worktrees 与共享仓库布局。
• GitHub：What are Git worktrees, and why should I use them? ：worktree 在现代并行与 Agent 工作流中的实际位置。