· 7 MIN · git · worktree · claude-code · workflow · -- PV ·

git worktree：多分支并行的标准答案，AI Agent 时代的基础设施

同时在改 3 个分支，其中一个突然要紧急修线上 bug。你的选择是 git stash 当前改动？切回去时还要重新 pnpm install？或者干脆 git clone 一份新的？

git worktree 是 git 内置的第三种选项 —— 同一个仓库共享 .git，但有多个并行的工作目录，每个目录检出不同分支，互不打扰。

本文从 3 个角度讲它：

  1. 工作模型 + 5 个核心命令，把概念讲透。
  2. 3 个真实场景，怎么把它融入日常。
  3. AI Agent 时代，worktree 如何成为 Claude Code / Codex 的隔离沙箱 —— 2026 年最大的新用法。

1. worktree 的工作模型

一个 git 仓库本质上是 .git/ 目录加一个工作目录（检出的文件）。worktree 让一个 .git/ 关联多个工作目录。

projectX/                    ← 主工作目录，检出 main 分支
├── .git/                    ← 唯一的元数据 (objects / refs / config / hooks)
└── src/...

../projectX-hotfix/          ← 第 2 个工作目录，检出 hotfix-xyz 分支
├── .git                     ← 这是一个文件，指向主仓库 .git/worktrees/hotfix
└── src/...

../projectX-experiment/      ← 第 3 个工作目录，检出 experiment 分支
├── .git                     ← 同上
└── src/...

3 个目录共用一份 objects/、refs/、hooks/、config，不复制、不浪费、push/fetch 一处统一。

跟其他做法对比：

方案对象共享切分支跨目录隔离主要缺点
切分支 (git checkout)✓慢（大仓尤甚）✗（同目录）IDE 重建索引，需先 stash
clone --shared✓快✓hooks/config 各一份，要维护 N 套
clone（完整）✗快✓占磁盘、初次慢
worktree✓快✓同分支只能开一个

worktree 的代价是一条硬约束：同一个分支最多只能被一个 worktree 检出。这是设计如此 —— 防止同分支在两个目录里出现冲突状态。有 --force 能绕开，99% 的场景不该用。

2. 五个你天天会用的命令

worktree 子命令很多，但日常 99% 的场景这 5 个就够：

git worktree add <path> <branch> —— 把已有分支检出到新路径。

git worktree add ../projectX-hotfix hotfix-xyz

新目录创建、分支自动检出，可以直接 cd 进去工作。

git worktree add <path> -b <new-branch> [<base>] —— 创建新分支并检出。

git worktree add ../projectX-pr1234 -b review/pr1234 origin/main

适合 review PR 或起临时分支，基底默认是 HEAD，可显式指定。

git worktree list —— 看当前都开了哪些。

$ git worktree list
/home/me/projectX             abc1234 [main]
/home/me/projectX-hotfix      def5678 [hotfix-xyz]
/home/me/projectX-experiment  9abc012 [experiment]

git worktree remove <path> —— 干净删除 worktree。

git worktree remove ../projectX-hotfix

会拒绝删除有未提交改动的 worktree。强删用 --force，但你应该先想想：那些改动是不是该提交。

git worktree prune —— 清理「路径已删除但元数据还在」的 worktree。

发生在你直接 rm -rf 一个 worktree 目录后（而不是用 worktree remove），git 不知情，worktree list 还会列。prune 把这些孤立记录清掉。

3. 三个真实场景

场景 A：线上紧急 hotfix，不打断当前 feature

你在 feature-X 上改了一半，IDE 开着 12 个 buffer，本地起着 dev server。线上 P1 要紧急修 bug。

传统做法：git stash → git checkout main → git checkout -b hotfix → 改 → 提交 → 切回 → git stash pop。中间 dev server 跟 IDE 状态全乱，stash 弹回来可能还冲突。

worktree 做法：

git worktree add ../projectX-hotfix -b hotfix-503 origin/main
cd ../projectX-hotfix
# 开新 IDE 窗口、起新 dev server、修 bug、提交、推
git push -u origin hotfix-503
cd ../projectX                    # feature-X 的窗口完全没动过
git worktree remove ../projectX-hotfix

主工作目录的 IDE、dev server、未提交改动零打扰。

场景 B：并行 code review，不污染主目录

review 同事的 PR 经常涉及「拉下来跑一下」。在主目录 checkout 会污染当前进度；clone 一份太重。

git fetch origin pull/1234/head:review-1234   # 拉 PR 到本地分支
git worktree add ../projectX-review review-1234
cd ../projectX-review
# 装依赖、跑测试、读代码、留 comment

# review 完
cd ../projectX
git worktree remove ../projectX-review
git branch -D review-1234

主目录跟 review 工作完全隔离，做完留无痕迹。

场景 C：长跑实验，失败直接丢

要试一个大重构、跑一组 benchmark、做一次架构性改动 —— 可能跑半天，可能失败。

git worktree add ../projectX-experiment -b experiment/parser-rewrite
cd ../projectX-experiment
# 砸代码、跑测试、改架构

成功 → git push + worktree remove；失败 → worktree remove --force + git branch -D experiment/parser-rewrite，主分支零痕迹。心理负担为零 —— 不用担心实验过程改了主目录某个文件忘了恢复。

4. AI Agent 时代：worktree 成为 sandbox

2026 年最大的工程变化是：Claude Code / Codex / Cursor agent 这些工具会自动在你电脑上长时间运行，改代码、跑测试、提 PR。

问题来了：你怎么让 agent 跟你同时在同一个仓库工作，不互相踩？

  • 直接让 agent 在主目录跑：agent 改了文件，你的 IDE 立刻看到 diff，正在写的代码半路被打断
  • 让 agent 切分支：你工作目录里没提交的改动瞬间消失，文件被覆盖
  • 让 agent 在另一份 clone 里跑：维护两套依赖、两份 hooks、两份 config

worktree 是干净的答案：agent 收到任务前，自动 worktree add，在隔离副本里做完整任务；你 review diff，合并或丢弃。

我自己常用的 Claude Code skill superpowers:using-git-worktrees 把这件事自动化了：

  1. dispatch agent 之前，检测当前 git 状态，自动创建 ../<project>-<task-id> 形态的 worktree
  2. agent 在那里改代码、跑测试、生成 commit
  3. 任务结束，如果 agent 没有任何改动（空 commit），自动清理 worktree 跟分支
  4. 如果有改动，返回 worktree 路径跟分支名给主线，让我去 review

整个过程主工作目录（连同我自己开着的 IDE、dev server、未提交改动）完全不被触碰。如果 agent 跑飞了、改了不该改的、跑了破坏性命令，代价局限在那个隔离 worktree 里，一行 worktree remove --force 回到原状。

这个组合的工程价值有 3 层：

层次无 worktree 的 agent+ worktree 的 agent
实验自由度怕跑乱主分支，prompt 写得保守，限制 agent 能力agent 可以激进改、激进试，坏掉就删
并行度1 个 agent 同时跑，否则互相覆盖N 个 agent 在 N 个 worktree 并行，互不干扰
主线影响任何 agent 动作都打断你的开发节奏主目录始终是你自己的工作状态，agent 不可见

可以这么概括：worktree 给 git 装上了沙箱；AI agent 时代，这个沙箱从「高级技巧」升级为「基础设施」。没有它，所有 agent 工作流都会反复被「主目录冲突」这个问题拖累。

5. 避坑清单

按踩过的频率排：

1. submodule 在新 worktree 里要重新 init。 git worktree add 不会自动 git submodule update。新 worktree 进去后跑一次：

git submodule update --init --recursive

2. pre-commit hooks 用绝对路径会跨 worktree 失效。 如果 hook 里写了主 worktree 的 venv / node_modules 绝对路径，在其他 worktree 跑时找不到。改成相对解析：

$(git rev-parse --show-toplevel)/path/to/tool

3. node_modules / venv 不在 git 里，每个 worktree 要重装。 不可避免的代价。用 pnpm 的 content-addressable store 或 uv 的全局缓存可以让实际下载接近零，但 install / sync 命令仍然每个 worktree 要各跑一次（链接文件需要重建）。

4. IDE 索引各自重建。 VSCode / JetBrains 把每个 worktree 当独立 workspace，索引各建一次，第一次打开有几十秒到几分钟。这其实是好事 —— 索引干净不混淆，跳转不会跨 worktree 跳乱。

5. 同分支不能开两个 worktree。 硬约束。--force 能绕过，但你大概率不该用 —— 同分支在两个目录被 git 跟踪为冲突状态，误操作容易丢提交。

6. 不要把 worktree 建在仓库目录内。 比如 git worktree add ./.worktrees/hotfix 看起来整洁，但 .gitignore、pagefind / eslint / vitest 这些工具会把它当成主仓库的一部分扫进去，可能扫描到自己的副本、可能产生循环 watch。永远建在仓库外的兄弟目录：../projectX-hotfix。

7. git worktree remove 不会自动删分支。 删 worktree 只解除目录跟分支的关联，分支本身还在。实验失败、分支没用，要 git branch -D <branch> 单独删，否则会越积越多。

6. 收尾

git worktree 不是 git 的小众功能，是「多个并行问题同时存在」的标准答案。

  • 单人单线程开发 → 切分支 + stash 还撑得住
  • 多分支并行（hotfix / review / experiment 同时存在）→ worktree 显著更优
  • AI agent 自动化（2026+）→ worktree 从「可选优化」变成「基础设施」

落地三步：

  1. 今天就用 worktree add 试一次 hotfix。感受跟 stash + checkout 的差别 —— 第一次用完不会想再回去。
  2. IDE 配置成「每个 worktree 一个 workspace」。VSCode 直接 code ../projectX-hotfix，JetBrains 是 Open 对应目录。每个窗口的运行状态、调试器、终端各自独立。
  3. 装一个 agent 工具，让它在 worktree 里跑任务。一旦体验过 agent 不打断你工作的感觉，就回不去了。
这篇怎么样？