Git Worktree 完全指南

什么是 Git Worktree

Git Worktree 是 Git 2.5+ 引入的功能，允许在同一仓库的不同目录中同时检出多个分支，每个目录都是独立的工作树。

┌─────────────────────────────────────────────────────┐
│                   仓库 (repo)                       │
│                                                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────┐ │
│  │ worktree-A   │  │ worktree-B   │  │ main     │ │
│  │ (fix-bug-1)  │  │ (feature-X)  │  │ (当前)   │ │
│  └──────────────┘  └──────────────┘  └──────────┘ │
└─────────────────────────────────────────────────────┘

核心概念

概念	说明
worktree	独立的工作目录，每个可以检出不同分支
bare repository	裸仓库（无工作目录）
linked worktree	关联到主仓库的工作树
main worktree	主工作树（.git 所在目录）

常用命令

1. 查看工作树列表

git worktree list

输出示例：

/path/to/repo          abc1234 [main]
/path/to/repo/fix-A    def5678 [feature-A]
/path/to/repo/fix-B    ghi9012 [feature-B]

2. 创建工作树

# 基本语法
git worktree add <path> <branch>

# 示例：在 fix-C 目录检出 tOS_A17_trunk 分支
git worktree add fix-C tOS_A17_trunk

# 示例：基于远程分支创建
git worktree add fix-C origin/tOS_A17_trunk

# 示例：创建并切换到新分支
git worktree add -b fix-C tOS_A17_trunk

3. 删除工作树

# 安全删除（推荐）
git worktree remove fix-C

# 强制删除（如果有未保存的更改）
git worktree remove --force fix-C

4. 移动工作树

git worktree move fix-C new-location/

5. 锁定/解锁工作树

# 锁定（防止意外删除）
git worktree lock fix-C

# 解锁
git worktree unlock fix-C

6. 清理无效工作树

git worktree prune

使用场景

场景一：并行开发多个功能

当前正在 main 分支开发，突然发现紧急 bug

# 不需要 stash 当前工作，直接开新工作树
git worktree add hotfix-urgent main
cd hotfix-urgent
# 修复 bug...
git commit -m "fix: 紧急修复"
cd ../main  # 回到原分支继续之前的工作

场景二：Code Review 时对比代码

# 可以在独立目录查看 PR 分支
git worktree add pr-review origin/pr/123

场景三：大型重构时保持分支独立

# 在独立工作树进行破坏性重构
git worktree add refactor-core develop
cd refactor-core
# 进行大规模重构...

场景四：在 Claude Code 中隔离实验

┌─────────────────────────────────────────────────┐
│  tOS_A17_trunk (主分支 - 稳定工作区)              │
│    └── worktree: fix-C (Bug修复分支)             │
│    └── worktree: feature-Y (新功能)              │
└─────────────────────────────────────────────────┘

注意事项

⚠️ 同一分支只能被一个工作树使用

# 错误示例：main 已被其他工作树使用
git worktree add another-main main
# 报错：fatal: 'main' is already being used by worktree at '/path/to/main-worktree'

⚠️ 删除工作树不会删除分支

git worktree remove fix-C
# 分支 fix-C 仍然存在，只是关联解除
git branch -d fix-C  # 需要手动删除分支

⚠️ 工作树之间共享 .git

修改 .git 内容（如 config、hooks）会影响所有工作树。但工作目录是独立的。

⚠️ 锁定状态的工作树无法删除

git worktree remove fix-C
# 报错：fatal: cannot delete worktree 'fix-C' (locked)

# 需要先解锁
git worktree unlock fix-C

常见问题排查

问题	解决方案
fatal: 'xxx' is already being used	该分支已在其他工作树使用，换分支名
cannot delete worktree (locked)	先 git worktree unlock
invalid path	检查路径是否合法（无特殊字符）
工作树目录丢失	用 git worktree prune 清理

总结

Git Worktree 是保持工作区干净、提升并行效率的利器，特别适合：

• 多任务并行开发
• 需要频繁切换分支的场景
• Claude Code 中隔离不同任务的工作区

---

快速命令参考

# 创建工作树
git worktree add <path> <branch>

# 查看列表
git worktree list

# 删除工作树
git worktree remove <path>

# 锁定/解锁
git worktree lock <path>
git worktree unlock <path>

# 清理无效工作树
git worktree prune