理解了第二章的分支机制之后,很快会遇到一个非常普遍的实际痛点:你正在 feat-login 分支上开发一个复杂模块,工作区里改了一半的文件还没有写完,测试跑不通,而且终端里还开着正在热加载的开发服务器。就在这个时候,生产环境突然出现一个紧急缺陷,需要你立刻基于 main 分支修改代码并发布;或者你希望同时开启两个 AI 编程助手,让它们在同一时间分别开发两个互不关联的需求。
在一个默认的 Git 仓库里,尽管你可以建出几十条分支,但整个项目只有一个工作目录,同一时刻只能展示某一条分支的源码。为了解决“一个仓库同时开展多条并行任务”的难题,Git 提供了 git worktree(工作树)机制。本章从单目录切分支的局限切入,先给出工作树的完整直观用法,再拆解它如何做到“多目录并行互不干扰、提交历史却实时互通”,最后推导同分支互斥规则与日常工程实践中的注意事项。
在只有一个工作目录时,面对上述紧急插单需求,之所以不能直接敲一句 git switch main 切过去修缺陷,是因为目录里还有改到一半的文件:如果 main 分支中这些文件的内容和当前分支不同,Git 为了防止覆盖掉你尚未保存的工作,会直接拦截并拒绝切换分支;而如果为了切走强行把跑不通的半成品代码提交到 feat-login,又会污染提交历史。
因此在不知道 git worktree 之前,开发者通常只有两种变通方案,但各自都存在明显的工程代价:
git stash 临时贮藏改动,切分支修完后再用 git stash pop 取回:这是很多人最常用的绕行做法。git stash 的作用是把当前工作区和暂存区里所有尚未提交的修改临时打包收进 .git 内部的贮藏栈(Stash)中,让工作目录瞬间恢复到上次提交时的干净状态,从而顺利执行 git switch main;等在 main 修完缺陷切回 feat-login 后,再运行 git stash pop 把刚才封存的半成品修改重新取回工作区。但这种来回打包切换在并行开发中很快会暴露三个局限:第一,默认只封存已被 Git 跟踪的文件,新创建但尚未 git add 的文件如果不额外加 -u 参数就会遗留在目录里;第二,由于自始至终只在同一个文件夹里替换文件内容,源码的批量改动会打断正在运行的热重载开发服务,并使编辑器符号索引和编译产物缓存失效;第三,切回原分支执行 git stash pop 恢复改动时,如果相关代码行已有变动,依然可能触发合并冲突。git clone 一份项目:虽然能够得到两个完全隔离的文件夹,但会重新从网络拉取整个项目的历史提交,在大型仓库里既耗时又占双倍硬盘体积;更重要的是,两份独立克隆体之间的本地分支互不可见,在目录 A 刚写完一次 commit,目录 B 完全看不到,必须来回推送到 GitHub 再拉取才能同步。git worktree 把“共享历史版本库”与“独立工作目录”结合在了一起。先看一遍完整的日常操作流,直观感受它的简洁程度。假设你目前位于主仓库目录 ~/proj/app,正在 feat-login 分支上改代码改到一半:
git worktree add -b hotfix ../app-hotfix main。Git 会在旁边的 ~/proj/app-hotfix 路径下新建一个干净的文件夹,里面直接铺好基于 main 创建的新分支 hotfix 的源码。../app-hotfix,修改代码、测试通过后执行 git add 与 git commit。此时哪怕还没有联网推送到远端,回到主目录 ~/proj/app 运行 git log --oneline --all(加上 --all 表示列出仓库内所有分支的提交记录,而不限于当前所在分支),也能立刻看到这个刚刚产生的 hotfix 提交记录。git worktree remove ../app-hotfix。临时工作目录随即被干净移除,而你在其中提交的 hotfix 分支依然安全保留在仓库历史中。只需看看 git worktree add 到底在硬盘上创建了什么,就能立刻明白为什么它能兼顾极速创建、零重复占用与历史互通。
最初通过 git init 或 git clone 创建的项目目录称为主工作树(Main Worktree),它内部保存着真正的 .git/ 文件夹。而通过 git worktree add 衍生出来的新文件夹称为链接工作树(Linked Worktree),打开它的根目录会发现:里面的 .git 根本不是一个文件夹,而是一个只有一行文本的普通文件,内容形如 gitdir: /path/to/app/.git/worktrees/app-hotfix。
图 1:主工作树与新增链接工作树的物理磁盘切分关系。绿色区域由所有工作树共同读写,蓝框与紫框区域则按工作目录严格隔离,确保两边并发编辑互不污染。
顺着这条路径回到主仓库 .git/worktrees/app-hotfix/,可以看到 Git 在这里为副目录单独存放了一组私有管理文件。通过这种结构切分,多个工作树之间严格划分出了“共享”与“独立”两个数据边界:
.git/ 中):包括存放全部历史提交与文件快照的 .git/objects/、保存所有本地分支指针的 .git/refs/heads/、记录远程仓库状态的 .git/refs/remotes/、第一节提到的 git stash 贮藏栈以及仓库配置。正因为历史对象和分支列表只有一份,新建工作树时既不需要拷贝庞大的历史库,也不需要重新联网;在任何一方执行 git commit 或 git fetch,其他所有工作树都能立刻看到变化。HEAD 指针(记录自己目前处于哪条分支),以及各自独立的暂存区文件 index。正因每个工作树都有自己的工作区文件、自己的 HEAD 和自己的 index,主目录改到一半的源码与暂存清单,完全不会影响副目录切换分支、筛选暂存或提交版本。如果在主工作树 ~/proj/app 当前正停留在 main 分支时,你试图执行 git worktree add ../app-second main 让第二个工作目录也停在 main 上,Git 会立刻拒绝并报错:
fatal: 'main' is already used by worktree at '/path/to/proj/app'
很多人初学时会疑惑为什么 Git 不允许两个目录同时打开同一个分支。借助上一节的共享边界,只需三步即可直接推导出答案:
main(.git/refs/heads/main)属于全局共享区,整个项目只有这一个指针。main 上,一开始两边的目录文件和指针都一致指向提交 M1。此时如果在工作树 A 修改文件并执行 git commit 生成新提交 M2,共享的 main 指针就会向前移动到 M2。HEAD 顺着共享的 main 已经指向了新版本 M2,但工作树 B 自己目录里的文件和暂存区仍然停留在旧版本 M1。如果此时在工作树 B 运行 git status,Git 对比 HEAD(M2)与目录现状(M1),就会误以为你刚才在工作树 B 亲手把 M2 里的全部新代码删改回去了,整个版本状态随之陷入混乱。
图 2:左侧展示两个工作树同时挂载在同一条可写分支 main 时,一方提交将破坏另一方工作区与 HEAD 的对应关系;右侧对比两种合规做法,分别是新建分支隔离开发与使用分离头指针只读验证。
因此 Git 定下铁律:同一条本地分支在同一时刻,只能在一个工作树中处于可写挂载状态。面对不同任务,遵循两种标准用法即可绕开这个限制:
git worktree add -b hotfix ../app-hotfix main),或者直接检出一条当前没有被其他工作树占用的已有分支(例如 git worktree add ../app-review feat-other;若该分支只存在于远端 origin,直接传入分支名时 Git 会自动为你建出本地对应分支并检出)。--detach 参数(例如 git worktree add --detach ../app-test main)。这样 Git 会直接把副目录的 HEAD 定格在当时 main 所指的具体 Commit 哈希上,不占用 main 这个分支名称;即便主目录之后在 main 上继续提交了十个新版本,副目录里的测试快照依然纹丝不动。围绕工作树的日常查看、迁移与销毁,Git 提供了一组简洁的维护命令来确保主仓库与副目录之间的互相指向始终一致:
git worktree list:列出当前仓库所有活跃工作树的目录路径、当前所处哈希以及占用的分支名称。git worktree move <旧路径> <新路径>:当需要把副工作树移动到别的文件夹时,务必使用该命令而不是直接用操作系统的 mv 或在文件管理器中拖拽。因为主仓库与副目录的 .git 文件互相记录了对方的路径,直接改名或移动会导致两边路径记录断裂。git worktree remove <路径>:安全删除指定的副工作树文件夹(若里面有未提交的修改,Git 会阻止删除以防误丢代码,确认要丢弃可附加 -f)。需要特别注意的是,git worktree remove 只负责销毁工作目录和临时控制文件,不会删除你在里面提交过的本地分支;待该分支的内容合入主干后,再按正常习惯使用 git branch -d <分支名> 清理分支指针即可。git worktree prune:如果因为习惯问题直接用 rm -rf 或在文件管理器里把副工作树文件夹删掉了,主仓库 .git/worktrees/ 里还会残留着失效记录,导致原分支依然处于“已被占用”的锁定状态。运行 git worktree prune 会自动清理所有已失效目录的残留管理记录,立刻释放被锁定的分支。在把 git worktree 融入日常项目开发时,还有三项高频工程细节需要提前规划:
~/proj/app 旁边放 ~/proj/app-wt-hotfix),彼此在文件系统中完全隔离。如果因为整理习惯必须建在主仓库内部的子目录(如 .worktrees/),务必第一时间将 .worktrees/ 写入主仓库的 .gitignore 文件,否则主仓库会把这个子目录当作成百上千个未跟踪的新文件,还会导致代码编辑器的全局文件搜索同时搜出两份重复代码。.gitignore 忽略的文件不会自动带过去:执行 git worktree add 时,Git 只会把已纳入版本控制的文件从历史快照恢复到新目录里。项目中那些被 .gitignore 排除在外的本地环境变量文件(如 .env、.env.local)以及本地安装的第三方依赖目录(如前端的 node_modules/、Python 的 .venv/),在新目录里默认都是不存在的。进入新工作树后,需要按需把本地 .env 复制一份过去并重新初始化依赖环境;在包管理工具选型上,像 pnpm install(通过本机全局存储硬链接复用依赖文件)和 uv sync(利用本地包缓存)可以在几秒内完成新工作树的依赖搭建,而不会把硬盘体积翻倍。3000 和 3001)。在多人或使用多个 AI 编码工具并发开发同一项目时,一种非常高效的工程模式是:把主工作树固定在干净的主干分支上专门用于审查代码与运行集成验证,同时为每一个并行的 AI 任务分别开出独立的 worktree 与新分支;各个任务互不覆盖彼此正在修改的文件与暂存区,全部完成并各自提交后,主工作树即可直接通过合并或下一章介绍的拣选机制汇总成果。