Git Worktree 允许在同一仓库的不同目录同时检出不同分支，共享版本库，解决多分支并行开发的痛点。
为什么需要 Worktree
传统方案要么多次克隆（浪费空间），要么频繁切换分支（未提交修改会丢失）。Worktree 共享 .git 目录，每个目录独立检出分支，修改互不干扰。
| 方式 | 磁盘占用 | 并行开发 |
|---|
| 多次克隆 | 2 倍 .git 大小 | 支持，同步麻烦 |
| 切换分支 | 1 倍 .git 大小 | 不支持 |
| Worktree | 1 倍 .git + 工作区 | 完美支持 |
核心机制
主版本库 + 链接工作树
- 主版本库：原始
.git 目录，存储所有分支、提交、对象库 - 链接工作树：独立目录，只有
.git 文件指向主版本库
1
2
| .git 文件内容：
gitdir: /workspace/t2v_data/.git/worktrees/xxx
|
分支锁定机制
同一分支不能在多个 worktree 中同时检出。主版本库的 .git/worktrees/[名称]/locked 文件记录锁定状态。
数据共享规则
| 内容 | 共享情况 |
|---|
| 提交、分支、标签 | 完全共享 |
| 暂存区 | 完全隔离 |
| 工作区文件 | 完全隔离 |
| 配置 | 主配置共享，局部配置隔离 |
| 钩子脚本 | 完全共享 |
核心命令
1
2
3
4
5
6
7
8
9
10
11
12
13
| # 创建 worktree
git worktree add ./repo-dev dev
git worktree add -b feature ./repo-feature main # 创建新分支
# 查看所有 worktree
git worktree list
# 删除 worktree
git worktree remove ./repo-dev
git worktree remove --force ./repo-dev # 强制删除（有未提交修改）
# 清理无效 worktree 元数据
git worktree prune
|
解决分支锁定问题
1
2
3
4
5
6
7
8
| # 查看锁定的 worktree
git worktree list
# 删除锁定的 worktree
git worktree remove /path/to/locked/worktree
# 或强制在新 worktree 检出已锁定分支
git worktree add --force ./repo-main main
|
典型场景
- 多分支并行开发：同时开发 feature 和修复 bug
- 临时查看历史版本：
git worktree add --detach ./temp v1.0 - IDE 自动创建：Cursor、VS Code 可能创建 worktree 预览分支
避坑指南
- 不要手动
rm worktree 目录，必须用 git worktree remove - worktree 不能嵌套创建
- 定期执行
git worktree prune 清理残留元数据
张芷铭的个人博客
Comments