Docs Library

Git Worktree 概念：多工作目录并行开发

系统解释 Git worktree 的概念——如何同时检出多个分支到不同目录，以及它解决的问题和适用场景。

适合谁看

想先理解历史图再看命令的人

前置知识

知道提交不是文件快照列表那么简单

常见风险

把概念页当命令说明页使用

一句话理解

Git worktree 让你可以在同一个仓库中同时检出多个分支到不同目录，每个目录有独立的工作区和暂存区，但共享同一个对象库和引用。

为什么需要 Worktree

在传统 Git 工作流中，一个仓库一次只能检出一个分支。当你需要切换任务时：

要么 stash 当前改动
要么提交半成品
要么创建新克隆

这些方案都有代价——stash 可能变质、半成品提交污染历史、新克隆浪费磁盘和网络。

Worktree 提供了第四种方案：在同一个仓库中，同时在多个目录中工作，每个目录对应不同分支。

Worktree 的核心概念

共享数据

所有 worktree 共享同一个 .git 目录中的：

对象数据库（objects）
引用（refs）
配置文件（config）
引用日志（reflogs）

独立数据

每个 worktree 拥有独立的：

工作区文件（working tree files）
暂存区（index）
HEAD 引用
部分 per-worktree 引用（如 refs/worktree/）

结构示意

Worktree 目录结构一个仓库可以同时拥有多个 worktree，每个 worktree 有独立的工作区和暂存区，但共享对象库和引用。

主 Worktree

project files

.git 目录

多 Worktree 共享

worktree A

worktree B

shared gitdir / objects

裸仓库

refs / objects / hooks / config

no checked-out worktree

核心操作

添加 worktree

# 在新目录中检出分支
git worktree add ../hotfix hotfix

# 创建并检出新分支
git worktree add ../feature-login -b feature/login

# 指定提交创建 worktree（detached HEAD）
git worktree add ../archive HEAD~3

列出 worktree

git worktree list

输出示例：

/path/to/main        abc1234 [main]
/path/to/hotfix      def5678 [hotfix]
/path/to/feature-login  fedcba [feature/login]

移除 worktree

# 安全移除
git worktree remove ../hotfix

# 如果 worktree 有未提交改动，先清理或强制移除
git worktree remove --force ../hotfix

锁定 worktree

防止 worktree 被意外移除（比如 worktree 在可移动磁盘上）：

git worktree lock ../hotfix --reason "USB 磁盘"

Worktree 不是万能方案

同一分支不能同时在多个 worktree 中被检出；worktree 不能嵌套；删除 worktree 之前无法删除其检出的分支。此外，虽然 worktree 共享对象库节省磁盘，但每个 worktree 的工作区文件是独立占用的——大仓库（如 monorepo）下多个 worktree 的磁盘占用仍然可观。

核心限制

同一分支只能在一个 worktree 中检出

# 如果 main 已经在主 worktree 中
git worktree add ../another-main main  # 错误！

Git 会阻止同一个分支在多个 worktree 中被检出，防止意外覆盖。

不允许嵌套

不能在已有的 worktree 目录中再次添加 worktree。

删除 worktree 后才可清理分支

包含某个分支的 worktree 必须被移除后，才能安全删除该分支。

典型使用场景

1. 紧急修复与日常开发并行

# 主目录正在开发 feature/login
git worktree add ../hotfix -b hotfix/critical-bug

# 在 ../hotfix 目录中修复 bug
# 不影响主项目的开发状态

2. PR 审查

# 在独立目录中审查 teammate 的 PR
git worktree add ../review-pr origin/feature/payment

# 审查完成后直接删除
git worktree remove ../review-pr

3. 多版本构建和测试

# 同时检出 v1 和 v2 版本
git worktree add ../release-v1 v1.0.0
git worktree add ../release-v2 v2.0.0

# 在两个目录中分别构建和测试

4. AI Coding Agent 并行工作

AI agent 可以用 worktree 在隔离的工作目录中并行处理多个任务，互不干扰。

Worktree vs 多克隆

维度	Worktree	多克隆
磁盘空间	共享对象库，几乎无额外开销	每个克隆完整复制对象库
网络开销	无额外 fetch 需要	每个克隆需要独立 fetch
引用同步	共享引用，一个 worktree 新建分支其他可见	需手动同步
隔离性	共享引用，分支名级隔离	完全隔离
误操作风险	一个 worktree 的 gc 可能影响其他	完全独立
易用性	需理解 worktree 概念	传统方式，无需学习

注意事项

磁盘占用

虽然 worktree 共享对象库，但每个 worktree 的工作区文件是独立占用的。如果你的仓库很大（如 monorepo），多个 worktree 的总磁盘占用可能很大。

Branch 管理

在其中一个 worktree 中创建的分支会自动在所有 worktree 中可见（因为共享 refs）。但删除分支前需要确保它没有被任何 worktree 检出。

不要对 worktree 目录运行 git init

worktree 目录不是独立仓库。对它运行 git init 会破坏 worktree 关联。

继续学习建议

理解 worktree 概念后，建议继续学习：

git worktree 命令的完整用法
workflows/parallel-work-with-worktree —— 并行开发工作流
workflows/ai-agent-worktree-mode —— AI agent 下的 worktree 使用模式
git worktree lock 和 git worktree prune 的维护操作