图解 Git Worktree：一个仓库，多个工作目录

Git Worktree 讲解视频的文字版。八个小节，从“worktree 到底是什么？”讲到你的第一条命令。

你正在某个功能分支上做到一半，生产环境突然炸了。大多数人会怎么做？把当前工作 stash 起来，切到 main，把 bug 修掉，然后再费劲把自己的思路重新拼回来。能用，但很折腾——每一次切换都要付出时间、注意力，通常还会丢掉 IDE 里干净的状态。

Git worktree 提供了一个更干净的解法。它不让你在同一个工作目录里反复横跳，而是让一个仓库长出多个工作目录，每个都检出到自己的分支上，而且可以同时存在。这篇文章和视频是同一套八个小节，你可以按自己的节奏慢慢读。

一个仓库，多个文件夹

1. Worktree 到底是什么？

worktree 其实就是磁盘上一个真实的目录，里面放着检出好的项目副本，并绑定到某个分支。平时你只有一个：项目文件夹，在一个分支上。而 worktree 让你可以拥有好几个——每个都是真实文件夹，各自在一个分支上——并且都指向同一个仓库。

能把它显示出来的命令很小，但很关键：

git worktree list

它会打印出每一个关联的文件夹，每个 worktree 一行，分别显示路径、提交和分支。不用克隆，也不重复存储 .git，只是从同一栋房子里多开了几扇门。

想象三个文件夹从一个 .git 目录向外展开：main、feature/auth、hotfix/login。每一个都是真实的目录，各自检出着自己的文件。关键在这里：每个文件夹都有自己的 HEAD，也就是各自独立的分支状态。

一个仓库。各自独立的工作树。

这就是全部的思维模型，剩下的都是细节。

共享仓库，独立工作树

2. 它底层是怎么实现的

表面的简单之下，藏着几个巧妙的机制。四个概念就能解释全部。

主工作树 vs 链接工作树

你原本的项目文件夹就是主工作树——它拥有真正的 .git 目录（内部称作 git-dir）。之后你创建的每个文件夹都是链接工作树，它并不自己存一份副本，而是通过 git-common-dir 指向主仓库。

独立的 HEAD

在一个文件夹里检出某个分支，其他文件夹纹丝不动，文件保持在原处。这是并行检出，而不是并行克隆——历史相同，沙箱各自独立。

共享的对象数据库

所有 worktree 都读写同一个 .git/objects 存储。你在某一个 worktree 里提交的 commit，会立刻对其他所有 worktree 可见。没有重复的 packfile，也比第二次完整克隆快得多。

唯一的规则：锁文件

Git 强制一条约束——同一个分支不能同时被两个 worktree 检出。硬要这样做，你会撞上：

fatal: branch 'feature/auth' is already checked out

这其实是特性，不是 bug：它防止两个工作树在同一个分支名上悄悄分叉。解决办法很简单——换一个分支，或者换一个 worktree 路径。

worktree 的核心概念

3. 传统流程 vs Worktree 流程

我们大多数人先学的都是“stash 再切换”那套舞步。把它和 worktree 的方式放在一起看看。

传统 Git 流程（折腾）：

  1. 你正深陷某个功能分支。
  2. 来了个紧急 bug。
  3. 你 git stash 当前进行中的工作，切到 main，修 bug，部署。
  4. 想回去——现在你得重建上下文：回忆 stash 里装了什么，重新应用（可能还有冲突），重新打开 IDE 早就忘掉的那些文件。

每一次切换都在消耗专注力，这就是摩擦。

Worktree 流程（解脱）：

  1. 保持原地不动。
  2. 直接开一个已经检出到 main 或 hotfix/login 的新文件夹。
  3. 在那里修、在那里部署。
  4. 你原来的功能文件夹毫发无损——没有 stash，没有切来切去。

传统流程 vs worktree 流程

两种方式都没错，但对于并行任务，worktree 优势明显：一个文件夹、串行上下文 对比 多个文件夹、并行上下文。

4. 目录结构长什么样

我们打开文件系统，看看它实际是什么样子。

你有一个主项目文件夹 my-project/，里面是熟悉的 .git/ 目录——真正的仓库数据就在这里。

现在为功能分支创建一个链接 worktree：

git worktree add ../my-project-feature-auth feature/auth

Git 会创建一个并列的新文件夹 my-project-feature-auth。这里有个微妙却重要的点：这个新文件夹里没有完整的 .git 目录，取而代之的是一个极小的 .git 文件——一个指针。

gitdir: /path/to/my-project/.git/worktrees/feature-auth

就这么一行，是整个 trick 的核心。它告诉 Git 真正的数据在哪，于是每个 worktree 既能保留自己的工作文件和 HEAD 状态，又能共享同一份提交历史和对象数据库。

链接 worktree 的目录结构

打开链接 worktree 里的 src/ 文件夹，你会看到 auth.ts——你的新功能代码。把它和 main 对比，差异一目了然。底层是同一个仓库，磁盘上却是完全独立的工作目录。你从不需要手动管理这些指针，Git 会替你维护好链接。

5. 常见使用场景

只要你需要让两个分支的上下文同时活着，worktree 就值回票价。

并行开发。 两个功能、两个分支、零干扰。不管是你自己同时做 feature/auth 和 feature/billing，还是两个开发者共用一个仓库，你只需要两个文件夹。没有 stash 排队，也没有“别动我未提交的改动”的焦虑。

代码评审。 你正深陷自己的分支，同事却要你审一个 PR。不必切走、丢了自己的节奏，直接在他的分支上开一个 worktree。跑测试、点 UI、给反馈——你原来的工作原封不动。

热修复（Hotfix）。 功能做到一半，生产环境炸了。在 main 或发布分支上开一个 hotfix worktree，修、测、部署、合并。做完回到功能工作，上下文零丢失。

改天再继续。 有时候进行中的工作太乱，既没法提交也不舍得 stash。把这个 worktree 原样停着，再开一个新的做下一个任务。几天后回来，停着的文件夹和你离开时一模一样——IDE 干净，git status 也干净。

worktree 常见使用场景

模式很简单：与其不停收拾你当前的桌子，不如直接再开一张桌子。

6. AI Agent 工作流

一旦 AI agent 登场，这个模式就更关键了——因为上下文才是新的瓶颈。

问题——上下文污染。 把好几个 agent 丢进同一个工作区，它们会争抢同样的文件和同一个上下文窗口。Agent A 重构 auth，Agent B 改写 API 路由，Agent C 改 UI——同时进行。共享的上下文越来越乱：过时的指令、对错误文件的假设、整体质量下滑。

解法——worktree 隔离。 给每个 agent 自己的 worktree。Agent A 拿到 auth 模块的专属目录，Agent B 在 API 包里干净地工作，Agent C 专注 UI。每个 agent 都有自己的干净工作目录和清爽上下文，互不串台。

规模化——Monorepo 并行。 在大型 monorepo 里，这种模式能优雅地扩展：通过专属 worktree 把每个 agent 限定到特定包。一切仍在同一个仓库里，但 agent 们在干净、并行的流里运作，谁也不踩谁的线。

worktree 在 AI agent 工作流中的应用

核心洞察是：worktree 给每个 agent 独立的工作目录和上下文——就像给每个人一张自己的桌子，而不是把所有人挤在一张桌子旁。它替代不了好的提示词，却能消除一整类由共享工作区带来的问题。

7. 动手试试：交互式沙盘

比起只读，你或许更想亲手戳一戳——讲解视频附带了一个沙盘，里面的命令不会碰你真实的仓库。

布局很直观：左侧是带 HEAD 位置的分支图，右侧是活跃目录的 worktree 面板，底部是模拟终端，还有所选 worktree 的文件树。

# 查看你拥有的所有 worktree
git worktree list

# 新建一个（面板和分支图里会立刻出现）
git worktree add ../my-project-hotfix hotfix/login

# 用完就清理掉
git worktree remove ../my-project-hotfix

你可以点任意 worktree 切换当前视图、查看它的文件，也可以用 Deploy Agent 按钮把不同 agent 分配到不同 worktree。随时点 Reset 即可恢复演示状态。

交互式 worktree 沙盘

在真实仓库上操作之前，这是个建立肌肉记忆的安全练习场。

8. 命令速查与下一步

整套 worktree 工具集都在这里——六个命令覆盖完整生命周期：

命令 作用
git worktree add <path> <branch> 在指定路径创建链接 worktree，可指定分支
git worktree list 列出所有 worktree 的路径、提交和分支
git worktree remove <path> 安全删除某个 worktree 及其工作文件
git worktree prune 清理已删除 worktree 留下的陈旧元数据
git worktree lock <path> 防止被意外删除（适合长时间运行的任务）
git worktree unlock <path> 准备就绪后解除锁定

现在就能复制去用的三条命令：

git worktree add ../my-project-feature-auth feature/auth
git worktree list
git worktree remove ../my-project-feature-auth

Git worktree 命令速查

整个脉络就是：一个仓库 → 多个文件夹 → 并行工作 → 干净的 agent 上下文。 现在你已经知道如何从一个仓库创建多个工作目录、保持上下文干净，并更高效地工作——无论是一个人，还是带着 AI agent。

这周就去建你的第一个 worktree 吧。你会好奇，以前没有它到底是怎么过来的。

Happy coding！

本文是 Git Worktree 讲解视频的文字版。文中的图片占位符（images/*.jpg）将替换为对应的视频帧。