Git Worktree 原理、实战与避坑指南

近期研究 Cursor 2.0 的多 Agent 模式时发现，其底层使用了 Git Worktree 来实现并行任务。初次接触时感到有些困惑，虽然平时常用 Git，但对 Worktree 指令了解不多。

查阅后发现，Worktree 允许在同一个 Git 仓库中同时维护多个工作目录，每个目录可检出不同的分支或提交。这解决了多任务并行时的冲突问题。

例如，正在开发 feature/login 分支时，若需紧急修复 release/1.5 的线上 Bug，传统做法是 Stash 当前改动并切换分支，或者克隆新仓库。前者可能导致 Stash 混乱，后者环境配置繁琐。IDE 重新索引和编译也会消耗时间。

Worktree 基于同一仓库创建独立工作目录，共享 .git/objects，但拥有独立的 HEAD、index 和工作区文件。

实战场景

1. 紧急修复：在项目根目录下创建新 worktree 检出目标分支。

git worktree add ../hotfix-1.5 release/1.5

此命令会在上级目录创建 hotfix-1.5 文件夹，检出 release/1.5 分支。修完 Bug 提交推送后，返回原工作目录继续开发，无需切分支或 Stash。

2. 历史版本验证：创建临时工作目录检出特定提交。

git worktree add --detach ../temp-check 4f1e2c3

--detach 参数表示不关联任何分支，直接检出某个提交（分离头指针状态）。在此目录测试验证后删除即可，不影响原工作目录。

3. 代码评审：为 PR 创建独立 worktree，拉取代码、跑测试、查看效果，用完即删。

注意事项与避坑

1. 分支独占性：同一分支不能同时在多个 worktree 中检出。若已检出 main 分支，另一 worktree 尝试检出会报错 branch 'main' already checked out。如需多处查看相同提交，可使用 --detach 或创建不同分支指向同一提交。

2. 清理记录：直接删除目录不会自动清除 Git 仓库中的 worktree 记录（位于 .git/worktrees）。正确做法是使用 remove 命令：

git worktree remove ../hotfix-1.5