小理同学1. 为什么需要worktree：并行开发场景下的现实痛点
1.1 一个真实的多任务现场
先还原一个我前几天遇到的场景。朋友在改一个订单模块，代码写到一半，线上突然报了个紧急问题，需要马上拉分支修复。他当时的处理方式是：把现有改动 git stash，切回主分支，拉一个 hotfix 分支，修完发布，再切回原来的分支，git stash pop。这一套流程看着没毛病，但实际操作中你总会遇到几个让人头疼的瞬间，比如 stash pop 时冲突了、切分支时发现刚才某个文件忘了保存、build 到一半被迫中断，又或者仅仅是“我改了哪几个文件”这件事本身，就已经记不清了。
这就是 git worktree 存在的意义。它一句话解释：让同一个 Git 仓库，拥有多个相互独立、互不干扰的工作目录。每个目录可以检出不同的分支，你可以一边在主目录继续开发新功能，一边在另一个目录紧急修 bug，两边各自 commit、各自 build、各自测试，完全不打架。
当时我就直接让朋友别折腾了，用 worktree 把 hotfix 单独开一个目录出来，两边同时开工，几分钟就搞定了。这个功能我用了几年，今天系统性地把它的原理、操作和坑讲清楚，适合已经能熟练使用 git branch、git checkout、git merge 的开发者进阶学习。
1.2 传统方案的局限：stash、clone 与 checkout
在没有 worktree 之前，想同时处理多个分支上的任务，我们通常只有三种思路，但每一种都有明显的代价。
第一种是 git stash 加 git checkout 反复切换。这种方案最伤的不是操作繁琐，而是你一直在“中断-恢复”循环里。开发的思路被打断，build 产物要重新生成，stash 里的内容放久了甚至可能自己都忘了里面存的什么。一旦 stash 期间代码库发生大量变更，pop 时冲突几乎是必然的。
第二种是直接 git clone 多份仓库。这种做法倒也简单粗暴，每个目录就是一个独立的完整仓库。但代价非常明显：存储空间翻倍，而且多份 clone 之间的分支、提交、标签完全各过各的，你在这份 clone 上新建的分支并不会自动出现在另一份 clone 里，靠 push/pull 来同步简直是给自己找罪受。
第三种是只用一个工作目录，靠 git branch 切换。这本身没有错，但有一个前提是：你真的每次只需要处理一个分支。如果你需要同时打开两个分支的代码对比，或者并行推进两个任务，单工作目录天然不支持这种用法。
这三种方案的共同痛点是什么？说到底，工作区只有一个，而任务有多个。worktree 解决的正是这个矛盾：仓库只有一个，但工作区可以开出多个。
1.3 worktree 解决的核心问题
git worktree 功能是从 Git 2.5 开始引入的，到 2.15 之后各种边界情况基本完善。它允许你在同一个仓库里同时检出多个分支到不同目录，这些目录共享同一个 .git 对象库、共享所有分支和提交记录，但每个目录拥有独立的文件状态、独立的暂存区、独立的 HEAD。
这意味着什么呢？打个比方，一个 Git 仓库就像一套房子的总配电箱，对象库就是总闸，所有电路都从这里接。worktree 相当于从同一块电表上拉出几路独立的插座，每个插座上插的电器（工作目录）之间互不干扰——你用微波炉不会影响另一边开着空调，只要你别在同一路插座上插两个大功率设备就行。
对照到实际场景，这套机制直接解决了四个高频需求：
- 紧急修复与日常开发并行。功能分支继续写着，hotfix 分支在另一个目录里修，互不打断；
- Code Review 更舒服。有人提了个 PR/MR，你直接
git worktree add一个目录来检出那个分支，边看代码边运行测试，看完就删，不污染主工作区； - 同一仓库多版本同时构建。比如一个目录是 main 分支，一个目录是某个 release 分支，两边各自跑构建、跑测试，不用排队等切换；
- 实验性改动零风险尝试。想在某个提交上试试新写法，又不想影响当前分支，直接开一个 detached HEAD 的 worktree 进去折腾就行。
这几个需求技术上并不算新问题，但 worktree 把这套操作从“勉强能做”变成了“优雅自然”，这就是它最大的价值。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. worktree 核心原理与工作方式
2.1 一个仓库，多个工作目录的底层机制
很多人第一次接触 worktree 时会觉得不可思议：一个仓库怎么可能同时检出两个分支？Git 的底层机制里到底发生了什么？
先说说普通仓库的结构。一个正常的 Git 仓库里，.git 是核心目录，里面保存着对象数据库（objects）、引用（refs）、HEAD、暂存区（index）等。你每次 checkout 一个分支，本质上就是：把 HEAD 指向某个分支引用，然后把该分支对应的快照内容写到工作目录里。
而当你执行 git worktree add 时，Git 做了这么几件事：
- 在主仓库的
.git/worktrees/<name>/下新建一个目录，里面放这个新 worktree 自己专属的 HEAD、index、per-worktree refs； - 在你指定的路径创建真实的文件目录，并把对应分支的文件内容完整检出到里面；
- 在这个新目录下创建一个
.git文件（注意，不是目录），内容是一行文本，指向主仓库的 gitdir 路径，格式类似：gitdir: /path/to/main-repo/.git/worktrees/<name>。
这个机制的巧妙之处在于：每个 worktree 的“身份信息”独立存储，但“内容数据库”完全共享。主仓库与所有 linked worktree 共享 objects（提交、树、二进制对象）、共享 refs（branches、tags），所以你在任何一个 worktree 里 git commit 之后，其他 worktree 能立刻看到新的提交记录；你在任何一个 worktree 里新建分支，其他 worktree 用 git branch 也能立刻看到。
但另一方面，每个 worktree 的工作区文件、暂存区、HEAD 又是完全独立的。在 A 目录里改了一半的文件，B 目录里完全看不到，B 的