同一个仓库、同一时间要干三件事:手上的功能还没写完,线上突然报 500 要立刻热修,同事又发来 PR 等你 review。多数人的做法是 git stash 存一下、切分支、修完再切回来——来回几次,stash 列表就堆成一串「WIP on xxx」,谁也不敢随便 pop。其实 Git 从 2.5 起就内置了 git worktree:一个仓库可以同时检出多个工作区,目录各自独立、对象库共享,切分支这件事不必在同一个目录里反复发生。

本文用一个真实工作流把 git worktree 讲透:主目录继续跑功能分支的长测试,另开两个目录分别做线上热修和 PR review,最后干净地清理。命令在 Git 2.5+ 均可用,Windows(Git for Windows)、macOS、Linux 表现一致。

它解决的不是「切分支慢」,而是「工作区只能有一个」

一个普通的 Git 仓库只有一个工作区和一个索引,所以「同时处于两个分支」在物理上不可能。worktree 的做法是:在仓库的 .git 目录里登记多个工作区,每个工作区有自己的 HEAD、索引和文件树,但共享同一个对象库和 refs。带来的直接好处是:

  • 不用重复下载历史:对象只存一份,第二个工作区几乎瞬间创建;
  • 一次 fetch 全局生效:任意工作区拉到的远程分支,其它工作区立刻可见;
  • 互不干扰:A 目录跑到一半的测试、B 目录改到一半的文件,彼此看不见。
维度克隆三份worktree 开三个
磁盘占用对象库重复三份,历史大时非常可观对象库共享,只多出各自的工作区文件
同步成本每份都要单独 fetch一次 fetch,所有工作区共享 refs
同分支并存可以,但容易各改各的、互相覆盖不允许同一分支被两个工作区同时检出
依赖目录各自安装同样各自安装(node_modules、vendor 不共享)
适用场景需要完全隔离(不同工具链、不同 hooks)并行开发、线上热修、PR review

一次完整的实战:三条战线同时开

第 1 步:确认起点干净

bash 主工作区
cd ~/code/shop
git status --short          # 有未提交改动先提交或 stash,别带着脏状态开工
git fetch origin --prune    # 顺便清掉远端已删除的分支引用

第 2 步:开一个热修工作区

线上问题不等人,但手上的功能分支也不能丢。新建一个工作区,从 origin/main 拉出热修分支:

bash 创建热修工作区
# 语法:git worktree add -b <新分支> <目录> <起点>
git worktree add -b hotfix/order-500 ../shop-hotfix origin/main

cd ../shop-hotfix
# 修改、测试、提交
git add -A
git commit -m "fix: 订单详情页 500,空优惠券导致除零"
git push -u origin hotfix/order-500
💡 小技巧:工作区目录建议放在主仓库同级(如 ../shop-hotfix),不要塞进主仓库内部。放在内部会让 IDE 把两份代码当成一个工程索引,git status 也会变慢。

第 3 步:再开一个 review 工作区

同事的分支可以直接检出,不需要打断你手头的任何工作:

bash 检出待 review 的分支
git worktree add ../shop-review origin/feat/coupon

# 进入后是 detached HEAD(因为检出的是远程跟踪分支)
cd ../shop-review
git log --oneline -5
composer install
php vendor/bin/phpunit

只读 review 用 detached HEAD 完全够用;如果需要在上面改代码,就换成 git worktree add -b review/coupon ../shop-review origin/feat/coupon,给它一个本地分支。

第 4 步:查看与清理

bash worktree 管理
# 列出所有工作区:路径、当前提交、分支
git worktree list
# /home/me/code/shop         3f2a1bc [feature/payment]
# /home/me/code/shop-hotfix  9d4e5f6 [hotfix/order-500]
# /home/me/code/shop-review  7c8b9a0 (detached HEAD)

# 热修合并后删除工作区
git worktree remove ../shop-hotfix

# review 目录里有改过的文件时,需要 --force
git worktree remove --force ../shop-review

# 如果目录是被手工删掉的,元数据还在,用 prune 清理
git worktree prune --dry-run
git worktree prune
目的命令
新建工作区并建分支git worktree add -b <分支> <目录> <起点>
检出已有分支git worktree add <目录> <分支>
列出git worktree list
删除git worktree remove <目录>(有改动加 --force)
清理失效记录git worktree prune
移动位置git worktree move <目录> <新目录>
锁定(外接盘/网络盘)git worktree lock <目录>

六个容易踩的坑

1. 同一个分支不能被两个工作区同时检出

这是设计上的硬限制,报错类似 fatal: 'main' is already checked out at '/path/shop'。想两个目录都改 main,正确做法是其中一个用新分支;--force 虽然能绕过,但两个索引改同一分支,最后必然互相覆盖。

2. 目录被手工删了,记录还留着

rm -rf ../shop-review 之后,git worktree list 仍会列出它,分支也可能被认为「已被检出」而删不掉。执行 git worktree prune 即可清掉失效登记。优先用 git worktree remove,而不是直接删目录。

3. 依赖目录和环境文件不会跟着复制

worktree 只共享 Git 对象,不共享 node_modules、vendor、.env、编译缓存。新工作区第一次用之前,该装的依赖还得装,.env 该拷还得拷。把这一步写进项目 README,团队里其他人会少踩一次。

4. 不要在 worktree 里再嵌套 worktree

把新工作区建在另一个工作区内部,会让文件被两个索引同时看见,git status 出现莫名其妙的未跟踪项。保持「所有工作区平级」是最省心的结构。

5. IDE 索引各算各的

VS Code、PhpStorm 都会为每个目录单独建索引,三个工作区就是三份缓存。这不是 bug,但要注意别在多个窗口同时开同一个文件改——Git 不会帮你合并未提交的修改。

6. 子模块与 LFS 要单独初始化

新工作区不会自动拉子模块和 LFS 对象:

bash 新工作区初始化
git submodule update --init --recursive
git lfs pull

什么时候不该用 worktree

场景更合适的做法
只想看一眼某个旧版本的某个文件git show v1.4.0:path/to/file
只需要临时验证一个提交git switch --detach <sha> 看完切回
需要完全隔离(不同 Git 版本、不同 hooks、不同全局配置)独立 clone,或用容器
目录放在网络盘、多人共用worktree 的锁与文件监听在共享盘上不可靠,建议各自 clone

总结

git worktree 的价值不在于省下几次 git switch,而在于把「并行的工作」真正分开:功能开发、线上热修、代码 review 各自有一个干净的工作区,互不打断,也不用再靠 stash 列表当临时仓库。用 add 开、list 看、remove 收、prune 兜底,四个命令就够日常使用。唯一要记住的硬规则是:同一个分支,只能在一个工作区里被检出。

分支可以并行,工作区不必唯一。