Skip to main content

Git worktree 是什么？

· 5 min read

git worktree 让多分支并行工作，一个目录 = 一个分支。

  • 核心机制：所有 worktree 共享一个 .git 数据库
  • 典型场景：边修 bug 边开发 feature，不切分支
  • code review：独立目录看 PR，不打断当前工作
  • 跑长任务：CI、build 不阻塞主工作区
  • superpowers 模式：一个 worktree 一个 agent，并行的关键
  • 使用注意：同一分支只能被一个 worktree checkout
  • 清理规则：删目录不够，必须 git worktree remove

一个目录 = 一个分支​

git worktree 解决了"切分支就要打断当前工作"的痛点。

传统的 git 工作流是单目录：你在 feature/new-login 上改代码，写到一半需要切到 hotfix 分支修个紧急 bug，要么 git stash 保存进度，要么 git commit 留下半成品 commit。改完 bug 切回来，又得 git stash pop，遇到冲突更麻烦。

worktree 让你同时有多个工作目录，每个目录独立 checkout 一个分支：

# 主工作区：继续开发 feature
cd ~/project
git checkout feature/new-login

# 临时开个目录修 bug
git worktree add ../project-hotfix -b hotfix/login-500
cd ../project-hotfix
# 修完直接 commit push
cd ~/project
git merge hotfix/login-500

两个目录的代码完全独立，互不干扰。

共享的 .git 数据库​

所有 worktree 共享一个 .git 目录，但每个 worktree 有自己独立的 HEAD 和 working tree。

工作原理不复杂：

project/                  # 主 worktree
project-hotfix/           # 副 worktree
project/.git/             # 共享的 git 数据库

这就意味着：

  • 任何 worktree 里 commit，其他 worktree 立即可见
  • branch、tag、reflog 是全局共享的
  • 每个 worktree 独立 stash、index、working tree

唯一的限制：一个分支同时只能被一个 worktree checkout。主 worktree 在 main 上，你就不能在副 worktree 也 checkout main。

实战场景​

边修 bug 边开发 feature​

最常见的用法：开发到一半，线上出了 bug 需要紧急修复，但当前 feature 还不能 commit。

# 当前在 ~/project 开发 feature，代码写到一半不能 commit
git worktree add ~/project-fix -b hotfix/critical-bug
cd ~/project-fix
# 修 bug、commit、push
cd ~/project
git merge hotfix/critical-bug

不需要 stash、不需要 commit 半成品、不需要切分支。两个目录互不干扰。

code review 不打断手头工作​

review 同事 PR 时，单独开个 worktree 看：

git worktree add ~/project-review pr-branch-from-colleague
cd ~/project-review
# 跑代码、看实现、留评论
cd ~/project  # 回到主工作区继续开发

review 完一个 worktree 直接删掉：

git worktree remove ~/project-review

跑长任务时继续开发​

跑 CI、跑测试、跑 build 都很费时，worktree 让你开个新目录跑这些，主目录继续干别的。

git worktree add ~/project-test test-branch
cd ~/project-test && npm install && npm test
# 回到主目录继续写代码

superpowers 模式：一个 worktree 一个 agent​

我看 superpowers 这个 agent framework 的时候，发现它核心模式就是：每个 agent 跑在自己的 worktree 里。

为什么 agent 框架爱用 worktree？

  • 隔离性：agent A 在 worktree 1 改代码，agent B 在 worktree 2 改代码，互不污染
  • 可回滚：agent 写出问题，删掉整个 worktree 重新来，比 revert 一堆 commit 干净
  • 并行：多个 agent 同时跑不同 feature，每个有独立分支，最后 merge

实际用法类似：

git worktree add /tmp/agent-task-1 -b agent/feature-1
cd /tmp/agent-task-1
# agent 1 在这里干活

git worktree add /tmp/agent-task-2 -b agent/feature-2
# agent 2 在这里干活
# 两个 worktree 独立工作，最后在主 worktree merge

这种模式适合长时间跑、多任务并行的场景。单 agent 串行任务用 worktree 是过度设计，普通 git flow 就够了。

注意事项​

一个分支只能被一个 worktree checkout

主 worktree 在 main 上，副 worktree 就不能 checkout main。要先切走才能在别处 checkout。

  • 清理要彻底：删目录不算，必须 git worktree remove <path>，否则 .git/worktrees/ 有僵尸条目
  • stash 是局部的：A worktree 的 stash，B worktree 看不到
  • 别在副 worktree 里建新 repo：所有 worktree 共享 git 数据库，git 命令作用于全局

总结​

git worktree 不是新东西（Git 2.5+ 就有了），但很多人不知道。它解决的核心问题是"多任务并发"——同时改多个分支、同时跑多个 agent、同时 review 和开发。

三个最常用命令：

  • git worktree add <path> <branch>：新建 worktree
  • git worktree list：查看所有 worktree
  • git worktree remove <path>：删除 worktree

不需要的时候别强行用，但需要并行的场景，worktree 是 Git 自带的最干净方案。

Read More​