Git Worktree 完全指南

一、什么是 Worktree

一句话：让你在同一个 Git 仓库上，同时拥有多个工作目录，每个目录可以 checkout 不同的分支。

传统方式的痛点

平时你只有一个工作目录：


my-project/          <- 只能同时在一个分支上

想同时开发两个功能？只能：

切来切去 git checkout（打断当前工作、要 stash）
或者 clone 两份仓库（浪费空间、同步麻烦）

Worktree 的方式


my-project/          <- main 分支
my-project-feat-a/   <- feature-a 分支
my-project-feat-b/   <- feature-b 分支

三个目录共享同一个 .git 仓库（对象库、历史、分支都是同一份），但各自有独立的工作区和索引。互不干扰，可同时打开、同时编译、同时跑 AI Agent。

关键特性

共享 .git 对象库 → 几乎不占额外空间（只多一份工作区文件）
每个 worktree 有独立的分支（Git 强制：同一分支不能在两个 worktree 同时 checkout）
每个 worktree 有独立的工作区状态（未提交改动互不影响）
删除 worktree 不影响仓库本身

二、安装

好消息：worktree 是 Git 内置功能，无需安装。

只要你的 Git 版本 ≥ 2.5（2015 年发布，现在几乎都是），就已经有了。

检查版本：

bash
git --version
# git version 2.39.0  <- 没问题

如果版本太老（不太可能），升级：

bash
# macOS
brew install git

# Ubuntu/Debian
sudo apt update && sudo apt install git

# Windows
# 下载 Git for Windows 最新版即可

三、核心命令

只有几个命令，记住就够用了：

命令	作用
`git worktree add <路径> <分支>`	新建 worktree
`git worktree list`	列出所有 worktree
`git worktree remove <路径>`	删除 worktree
`git worktree prune`	清理失效的 worktree 记录
`git worktree move <旧> <新>`	移动 worktree

四、实战用法

假设你有个项目在 ~/code/my-project，当前在 main 分支。

1. 基于现有分支创建 worktree

bash
cd ~/code/my-project

# 在 ../my-project-feat-a 目录，checkout 已有的 feature-a 分支
git worktree add ../my-project-feat-a feature-a

2. 创建新分支并同时建 worktree（最常用）

bash
# 基于当前 HEAD 创建新分支 feature-b，并放到新目录
git worktree add ../my-project-feat-b -b feature-b

# 基于 main 创建（推荐，避免基于脏分支）
git worktree add ../my-project-feat-b -b feature-b main

3. 查看所有 worktree

bash
git worktree list

输出示例：


/home/you/code/my-project          abc1234 [main]
/home/you/code/my-project-feat-a   def5678 [feature-a]
/home/you/code/my-project-feat-b   9ab0123 [feature-b]

4. 在 worktree 里正常工作

bash
cd ../my-project-feat-b
# 这里就是普通的 git 仓库，随便改、随便提交
git status
git add .
git commit -m "feat: xxx"
git push -u origin feature-b

5. 删除 worktree

bash
# 先确保没有未提交的改动，然后：
git worktree remove ../my-project-feat-b

# 如果里面有改动想强制删：
git worktree remove --force ../my-project-feat-b

分支本身不会被删，只是移除工作目录。

五、配合 AI 并行开发的典型流程

这是你最关心的场景：

bash
cd ~/code/my-project

# 给每个 AI 任务开一个独立 worktree + 分支
git worktree add ../proj-ai-task-1 -b ai/task-1 main
git worktree add ../proj-ai-task-2 -b ai/task-2 main
git worktree add ../proj-ai-task-3 -b ai/task-3 main

git worktree list

然后：


终端1: cd ../proj-ai-task-1  -> 跑 AI Agent #1
终端2: cd ../proj-ai-task-2  -> 跑 AI Agent #2
终端3: cd ../proj-ai-task-3  -> 跑 AI Agent #3

每个 Agent 在自己的目录、自己的分支里干活，物理上不可能踩到别人。

完成后：

bash
# 各自 push
cd ../proj-ai-task-1 && git push -u origin ai/task-1
cd ../proj-ai-task-2 && git push -u origin ai/task-2

# 回到主目录，走 PR / merge 流程
cd ~/code/my-project
git fetch
# 逐个 review 合并，处理可能的 merge 冲突

关键约定：

一个 worktree = 一个分支 = 一个 Agent，绝不混用
每个 worktree 都从 main 最新拉出，减少后续冲突
合并前一定要 review + 跑测试，别让 AI 直接 push main

六、常见问题 & 注意事项

❌ 同一分支不能在两个 worktree 同时 checkout

bash
git worktree add ../dup feature-a
# fatal: 'feature-a' is already checked out at '.../my-project-feat-a'

这是 Git 的保护机制。要并行，就每个 worktree 用不同分支。

⚠️ 删除目录的正确姿势

不要直接 rm -rf 删 worktree 目录，会留下脏记录。用：

bash
git worktree remove <路径>

如果已经手贱删了，清理：

bash
git worktree prune

📁 目录放哪？

放在主仓库旁边（../xxx）比较整洁
别放在主仓库内部（会被 git 当成未跟踪文件）
建议统一命名，比如都加 -wt- 前缀，方便识别

🧹 定期清理

bash
git worktree list          # 看有哪些
git worktree remove xxx    # 删掉不用的

💡 小技巧：把 worktree 加到忽略

如果 worktree 目录不小心放在了仓库内，加到 .gitignore：


*-wt-*/

七、一句话总结

Worktree = 一个仓库，多个工作目录，各自独立分支，共享历史。 是并行开发（尤其多 AI Agent）最干净、最可靠的隔离方案，Git 原生、零成本。

vscode的worktree插件

https://github.com/jackiotyu/git-worktree-manager/blob/HEAD/README.zh-CN.md