夜雨聆风我之前写过一篇文章介绍Superpowers中工作树的引入：Superpowers高效执行是怎么实现的？
今天我完整的给大家分享一下为什么要使用git工作树以及其常见的使用方法。
工作树worktree是Git 2.5+ 引入的功能，允许一个仓库拥有多个工作区，每个工作区可检出不同分支。也就是允许你在同一个代码仓库中同时检出多个分支到不同的目录，每个目录拥有独立的文件系统状态，但共享相同的 Git 历史。
一、为什么要使用git工作树 不使用 Worktree 的弊端 使用 Worktree 的好处（这也是 CC 默认的做法） 不使用 Worktree 的弊端 使用 Worktree 的好处 不使用 Worktree 的弊端（痛苦流程） 使用 Worktree 的好处（优雅流程） 场景一：代码写一半，突然要修线上紧急 Bug（最经典痛点） 场景二：前端多版本/多分支并行调试（日常痛点） 场景三：AI Agent 并行干活（我正在经历的场景） 对比总结 git worktree隔离环境的特点 我什么时候要用它？ 二、git工作树worktree常见使用方法 1.合并分支 2.清理工作树 3.批量清理脚本 4.常见错误 1、创建工作树和分支 2、查看工作树 3、工作树收尾工作 三、补充知识
一、为什么要使用git工作树
不使用git工作树就像是一个单一工作台，而使用工作树就拥有了多个工作台。
不用 Worktree（单工作台）： 我只有一个厨房操作台。我正在做一道复杂的菜（开发新功能），切了一半的菜、各种调料摆满了一桌子。突然老板让我立刻去煮一碗面（修紧急 Bug）。我必须把桌上的菜全部收进冰箱（git stash），把案板洗干净（git checkout），煮完面后，再把冰箱里的菜拿出来（git stash pop）继续做。极其折腾，因为可能有文件冲突，容易出错。
用 Worktree（多工作台）： 我有好几个厨房操作台。我在 1 号台做复杂的菜，突然要煮面，我直接走到 2 号台，上面干干净净，直接煮面。煮完面把 2 号台收拾了（git worktree remove），回到 1 号台继续做我的菜，一切原封不动，完全不打断。（一个git目录下）
为了让大家了解git工作树的威力及为什么要用工作树，我们一起来看以下三个工作场景。
场景一：代码写一半，突然要修线上紧急 Bug（最经典痛点）
背景：我在我的 React SPA 项目里开发 feature/audio-player 分支，改了十几个文件，代码很乱，还没法 commit。突然，线上 main 分支出了一个严重的白屏 Bug，需要我立刻切过去修。
不使用 Worktree 的弊端（痛苦流程）
被迫暂存：我必须执行
git stash（如果还有没 track 的新文件，还得加-u参数）。环境重建（最烦人）：我执行
git checkout main。此时，我的 VSCode 开始疯狂重新索引，TypeScript 语言服务重启，ESLint 重新加载。因为分支变了，我可能还得重新跑一次pnpm install。修完切回：Bug 修完了，我执行
git checkout feature/audio-player。IDE 又要重新索引一遍，我可能又得等它转圈圈。恢复现场：执行
git stash pop。运气好直接恢复；运气不好，产生冲突，我还得去解冲突。总结：整个过程打断了我的心流，浪费了大量时间在“等 IDE 索引”和“重装依赖”上，心智负担极重。
使用 Worktree 的好处（优雅流程）
创建分身：在终端敲一句： git worktree add ../hotfix-bug main平行宇宙：Git 瞬间在我的项目旁边创建了一个 hotfix-bug文件夹，里面是干净的main分支代码。互不干扰：我用 CC 打开这个新文件夹去修 Bug。我原来的 feature/audio-player文件夹里的代码、没保存的草稿、正在运行的 dev server，完全不受影响！用完即毁：Bug 修完并 push 后，执行 git worktree remove ../hotfix-bug。分身消失，我回到原来的文件夹继续写我的播放器，仿佛什么都没发生过。
场景二：前端多版本/多分支并行调试（日常痛点）
背景：我的音频项目马上要发版了，我需要在本地同时跑 release-v1.0 和 main (开发版) 两个环境，对比一下新版的音频波形渲染有没有性能回退。
不使用 Worktree 的弊端
我只能开两个终端，在同一个目录下反复 git checkout。或者拷贝一个副本到别的目录，用IDE打开两个目录或者开两个终端。最后把自己绕晕了，都不知道哪个目录是最新的了，两个目录git目录是独立的，合并文件也是一个灾难。致命问题：每次 checkout， node_modules可能不匹配，我不得不反复执行npm install。而且我无法在浏览器里同时打开两个版本的页面进行左右对比，因为端口和代码状态在物理上是互斥的。
使用 Worktree 的好处
执行 git worktree add ../v1-release release-v1.0。现在我有两个物理目录：主目录跑 main，../v1-release跑v1.0。我可以在两个目录分别 pnpm install并启动 dev server（比如一个跑 3000 端口，一个跑 3001 端口）。爽点：我可以在浏览器开两个 Tab，同时、实时地对比两个版本的 UI 和性能，这在单 worktree 下是绝对做不到的。
场景三：AI Agent 并行干活（我正在经历的场景）
背景：我在使用 Claude Agent（或者 Cursor/Copilot Workspace 等 AI 工具）帮我重构代码。我希望 AI 在后台帮我写代码，同时我自己要在前端继续改别的页面。
不使用 Worktree 的弊端
如果 AI 和我在同一个目录工作，必定会发生文件覆盖和 Git 冲突。AI 刚改完 App.tsx，我下一秒也保存了App.tsx，两个修改就打架了。如果让 AI 用 git stash或切分支，它会频繁打断我的工作。
使用 Worktree 的好处（这也是 CC 默认的做法）
Claude Agent 会自动执行 git worktree add .claude/worktrees/agent-xxx。AI 在它的“隔离沙盒”（worktree）里随便改、随便 commit，绝对不会碰我主目录里的任何文件。 等 AI 干完活了，我再通过 git merge或git cherry-pick把 AI 的代码合并到我的主分支。这就是为什么我之前看到那么多 agent-*残留的原因：AI 每次接任务都会建一个独立的 worktree 保护自己和我，只是它干完活后没有自动清理（remove）而已。
对比总结
| 未提交的代码 | stash，容易忘，pop 时可能冲突 | 无需 stash |
| IDE 性能 | ||
| 依赖安装 | npm install | node_modules |
| 并行运行 | 不可能 | 轻松实现 |
| 多人/AI协作 | ||
| 代价 | node_modules） |
git worktree隔离环境的特点
| 物理隔离 | |
| 分支专属 | feat/payment-terminal） |
| 共享历史 | .git 对象数据库，节省空间 |
| 并行开发 | |
| 原子性 |
我什么时候要用它？
如果我只是一个人在一个小项目里线性开发（做完 A 做 B），我完全不需要 worktree，git checkout 足够了。
但是，只要我遇到以下任何一种情况，Worktree 就是该上场了：
“代码写了一半，突然要切分支！”（不想 stash） “要同时独立跑两个分支看效果！并行开发”（需要并行环境） “我要让 AI / 脚本在后台帮我改代码，我自己还要继续写！”（需要物理隔离）
二、git工作树worktree常见使用方法
1、创建工作树和分支
git worktree add ./worktrees/feature+model-provider-management -b feature+model-provider-management
执行后会创建目录一个和分支名一样的目录。
2、查看工作树
git worktree list
可以看到上面会有两个worktree，一个是main（git默认自带），一个是claude创建的。
3、工作树收尾工作
如果你在工作树开发完成后，需要合并代码和删除不再使用的工作树，下面把场景的操作给大家做一个梳理。
操作顺序：合并分支→先删工作树 → 再删分支（避免“分支正被使用”错误）
1.合并分支
# 将 feature+model-provider-management 合并到当前分支（main）
git merge feature+model-provider-management
2.清理工作树
# 删除工作树
git worktree remove <工作树路径>
# 删除示例
git worktree remove ~/Projects/yqj-audio-local-helper-react-spa/.claude/worktrees/feature+model-provider-management
# 清理 Git 内部引用
git worktree prune
3.批量清理脚本
如果你的Code Agent在本地给你生成了多个工作树，要一个一个的删除觉得很麻烦。
那么也批量的方法，我把脚本分享给你：
建一个sh脚本名为：check-claude-worktrees.sh，内容如下：
#!/bin/bash
WORKTREE_DIR=".claude/worktrees"
MAIN_BRANCH="main" # 改为你实际的主分支名，如 master / main / develop
echo " 检查工作树是否已合并到 $MAIN_BRANCH："
echo "===================================================================="
for wt in "$WORKTREE_DIR"/agent-* "$WORKTREE_DIR"/improve-llm-subtitle-segmentation; do
if [ -d "$wt" ]; then
# 获取该 worktree 的当前分支名（通常为 feature/xxx 或 agent-xxx）
BRANCH=$(cd "$wt" && git symbolic-ref --short HEAD 2>/dev/null || echo "unknown")
# 检查是否已合并到主分支
if [ "$BRANCH" != "unknown" ] && git merge-base --is-ancestor "$BRANCH" "$MAIN_BRANCH" 2>/dev/null; then
STATUS=" 已合并"
else
STATUS=" 未合并"
fi
# 检查是否有未提交更改（关键！避免误删重要代码）
UNTRACKED=$(cd "$wt" && git status --porcelain | grep -v "^?? .git/" | wc -l)
MODIFIED=$(cd "$wt" && git status --porcelain | grep -E "^[^?]" | wc -l)
if [ "$UNTRACKED" -gt 0 ] || [ "$MODIFIED" -gt 0 ]; then
CHANGES=" $UNTRACKED untracked + $MODIFIED modified"
else
CHANGES="✓ 干净"
fi
echo "$(basename "$wt") | branch: $BRANCH | $STATUS | $CHANGES"
fi
done
再建一个脚本：cleanup-worktrees.sh
#!/bin/bash
# 用法: ./cleanup-worktrees.sh [-f] [-f]
# 示例: ./cleanup-worktrees.sh -f -f (强制清理锁定的无效worktree)
FORCE_FLAGS=""
while [[ "$#" -gt 0 ]]; do
case "$1" in
-f|--force) FORCE_FLAGS="$FORCE_FLAGS -f"; shift ;;
*) echo "未知参数: $1"; exit 1 ;;
esac
done
git worktree list | tail -n +2 | awk '{print $1}' | while read -r wt; do
if [ ! -d "$wt" ]; then
echo " 正在清理无效记录: $wt"
# 动态拼接 force 参数
git worktree remove $FORCE_FLAGS "$wt"
fi
done
echo " 清理完成！当前剩余 worktree："
git worktree list
执行效果如下图：
4.常见错误
有未提交代码删除失败
git worktree remove /Users/davidezheng/Projects/xx助手/easyApprove2/.worktrees/history-list-enhancement
fatal:'/Users/davidezheng/Projects/xx助手/easyApprove2/.worktrees/history-list-enhancement' contains modified or untracked files, use --force to delete it
该工作树目录中 存在未提交的更改（可能是你调试时改了代码、生成了日志、或者有临时文件） Git 拒绝直接删除，防止你意外丢失未保存的工作
解决办法：先提交代码合并分支后再删除
被锁定了删除失败
git worktree remove /Users/davidezheng/Projects/yqj-audio-local-helper-react-spa/.claude/worktrees/agent-a4bdc31d fatal: cannot remove a locked working tree, lock reason: claude agent agent-a4bdc31d (pid 96530) use 'remove -f -f' to override or unlock first
工作树被 Claude Agent 进程（PID 96530）锁定了。Git 为了防止正在运行的 AI Agent 或后台任务在操作文件时目录被意外删除，自动加上了锁。
解决办法：先解锁再删除
# 1. 手动解除锁定
git worktree unlock /Users/davidezheng/Projects/yqj-audio-local-helper-react-spa/.claude/worktrees/agent-a4bdc31d
# 2. 正常删除（如果还有未提交文件，仍需加一个 -f）
git worktree remove /Users/davidezheng/Projects/yqj-audio-local-helper-react-spa/.claude/worktrees/agent-a4bdc31d
最后在删除分支之前，建议先执行下面两条命令分别查看所有已经合并到main的分支和所有没有合并到main的分支。
# 查看哪些分支已合并到 main，可安全删除
git branch --merged main
# 查看哪些分支没有合并到 main
git branch --no-merged main
三、补充知识
每个工作树独立维护自己的 HEAD 和工作文件状态。
Git 合并操作只认“分支名”，不认“工作树路径”。
每个工作树（worktree）在创建时就绑定到一个特定的分支，这个绑定是固定的。多个工作树必须对应不同分支。“一个分支，一个工作树” —— 1:1 绑定关系。
你在主工作区（比如
./）执行git checkout main、git switch dev等操作，完全不会影响其他工作树的状态。同样，在工作树目录中切换分支，也不会影响主工作区或其他工作树。
