同一个仓库、同一时间要干三件事:手上的功能还没写完,线上突然报 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 步:确认起点干净
cd ~/code/shop
git status --short # 有未提交改动先提交或 stash,别带着脏状态开工
git fetch origin --prune # 顺便清掉远端已删除的分支引用
第 2 步:开一个热修工作区
线上问题不等人,但手上的功能分支也不能丢。新建一个工作区,从 origin/main 拉出热修分支:
# 语法: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 工作区
同事的分支可以直接检出,不需要打断你手头的任何工作:
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 步:查看与清理
# 列出所有工作区:路径、当前提交、分支
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 对象:
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 兜底,四个命令就够日常使用。唯一要记住的硬规则是:同一个分支,只能在一个工作区里被检出。
分支可以并行,工作区不必唯一。