xxyi
← notes

git worktree

2026-05-02

什么是 git worktree, why?

整个展开的项目目录就称之为 worktree 。 git worktree 即允许多个 worktree checkout 不同的分支同时存在，这些 worktree 属于同一个 git 仓库，共享一个 .git 文件夹。只有 main 分支的工作树有真正的 .git，其他的 .git 都指向真正的 .git。

一个 branch 只能对应一个工作树。

tips：主工作树也可以从 main 分支切到其他分支，.git 只留在其中。git rev-parse --git-common-dir 命令直接给出主工作树 .git 的路径。

为什么要有 git worktree？

本地多分支不同功能同时开发需要 git worktree。如果没有 git worktree 会有哪些不便？

  1. 未完成的工作被迫中断。 在开发分支上做工作，还没到能 commit 的程度。另一个分支爆了紧急 bug，需要处理。切出去之前需要 git stash 暂存，回来以后 git stash pop。而 stash 是个栈，容易混乱和丢失内容。
  2. 长时间任务阻塞。 分支 A 的测试是长时的，因为要等测试，不能切去其他分支。
  3. 只能用多份 git clone 仓库来处理多分支开发，难以管理。

结合最新的 vibe coding（或者说结合文档驱动 / 测试驱动的 AI 编程），从"串行 AI 开发"→"并行多分支同时 AI（多实例）开发，最后 merge"，效率提升是分支数的倍数（不考虑大脑来回切上下文带来的消耗与难度）。

git worktree 的直觉模型

       ┌──────────────────────────┐
       │  仓库 (.git/ 数据库)      │  ← 真正的核心
       └─────────────┬────────────┘
                     │
        ┌────────────┼────────────┐
        ↓            ↓            ↓
   主工作树      附属工作树1   附属工作树2
  (恰好持有     (链接到仓库)   (链接到仓库)
   .git/目录)

关键：所有工作树共享一套 git 仓库。

~/proj/                          ← 主 worktree (展开 main)
├── .git/                        ← 真正的仓库, 大本营
│   ├── objects/
│   ├── refs/heads/main          → SHA_X
│   ├── refs/heads/feat-a        → SHA_Y
│   ├── refs/heads/feat-b        → SHA_Z
│   ├── worktrees/               ← 记录所有附属 worktree 的元数据
│   │   ├── proj-feat-a/
│   │   └── proj-feat-b/
│   └── HEAD → refs/heads/main
├── src/  README.md  ...         ← main 的代码
│
~/proj-feat-a/                   ← 附属 worktree (展开 feat-a)
├── .git                         ← 注意是文件, 不是目录!
│   └── (一行字: gitdir: ~/proj/.git/worktrees/proj-feat-a)
├── src/  README.md  ...         ← feat-a 的代码
│
~/proj-feat-b/                   ← 附属 worktree (展开 feat-b)
├── .git                         ← 同样是文件
│   └── (一行字: gitdir: ~/proj/.git/worktrees/proj-feat-b)
├── src/  README.md  ...         ← feat-b 的代码

git worktree 常用命令

# 新建 worktree (最常用形式: 新建分支并 checkout 到新目录)
git worktree add ../proj-feat-a -b feature-a
 
# 基于已有分支
git worktree add ../proj-feat-c some-branch
 
# 列出所有 worktree
git worktree list
 
# 删 worktree (先删目录, 再 prune; 或直接 remove)
git worktree remove ../proj-feat-a
git worktree prune                   # 清理失效引用

与多 AI 实例（claude code / codex）结合

  • 在不同的工作树（目录）下开 claude code 或者 codex
  • 各工作树下用自己虚拟环境（比如 python 用 uv），不要共享环境，最后合分支的时候在依赖上取"公约数"