git-worktrees

Git Worktrees

概述

Git worktree 允许你从同一个仓库创建多个工作目录，每个目录检出不同的分支。无需切换分支，即可同时处理多个分支。

何时使用 Worktree

✅ 最适合：

• 堆叠式 PR 开发（每个 PR 使用一个 worktree）
• 开发功能期间处理紧急热修复
• 并行开发多个功能
• 在隔离环境中进行代码审查
• 测试跨分支交互
• 同时运行多个开发服务器

⚠️ 以下情况可考虑替代方案：

• 磁盘空间有限（worktree 会复制工作目录）
• 简单切换分支即可满足需求
• 一次只处理一个分支

基本工作流

创建 Worktree

新分支：

# Create worktree with new branch
git worktree add ../worktrees/feature-auth -b feature/authentication

# Navigate to worktree
cd ../worktrees/feature-auth

现有分支：

# Create worktree from existing remote branch
git worktree add ../worktrees/feature-profile feature/user-profile

# Or from origin
git worktree add ../worktrees/review origin/feature/pr-to-review

列出 Worktree

git worktree list

# Output:
# /Users/dev/project              abc123 [main]
# /Users/dev/worktrees/f-auth     def456 [feature/authentication]
# /Users/dev/worktrees/f-profile  ghi789 [feature/user-profile]

移除 Worktree

# Remove worktree (deletes directory)
git worktree remove ../worktrees/feature-auth

# Or manually delete directory and prune
rm -rf ../worktrees/feature-auth
git worktree prune

目录结构

推荐布局：

/Users/dev/
├── my-project/              # Main repository
│   ├── .git/               # Git database
│   ├── src/
│   └── ...
└── my-project-worktrees/    # All worktrees here
    ├── feature-auth/       # feature/authentication branch
    ├── feature-profile/    # feature/user-profile branch
    ├── hotfix-urgent/      # hotfix/urgent-fix branch
    └── review-pr-123/      # Reviewing PR #123

使用场景：堆叠式 PR

非常适合堆叠式 PR 工作流——每个 PR 使用一个 worktree：

# Create worktree for each PR in stack
git worktree add ../stack/pr-001 -b feature/001-base-auth
git worktree add ../stack/pr-002 -b feature/002-user-profile
git worktree add ../stack/pr-003 -b feature/003-admin-panel

# Work in each independently
cd ../stack/pr-001
# Implement base auth
git commit -am "feat: base authentication"
git push -u origin feature/001-base-auth

cd ../stack/pr-002
# Already on feature/002-user-profile branch
# Implement user profile (depends on pr-001)
git commit -am "feat: user profile with auth"
git push -u origin feature/002-user-profile

cd ../stack/pr-003
# Implement admin panel (depends on pr-002)
git commit -am "feat: admin panel"
git push -u origin feature/003-admin-panel

使用场景：并行开发

同时运行多个开发服务器：

# Terminal 1: Main feature development
cd /project-worktrees/feature-new-ui
npm install
npm run dev  # Server on port 3000

# Terminal 2: Urgent hotfix (different branch)
cd /project-worktrees/hotfix-critical
npm install
npm run dev -- --port 3001  # Server on port 3001

# Both running simultaneously without branch switching

使用场景：代码审查

在隔离环境中审查 PR：

# Create worktree for PR review
git worktree add ../review/pr-456 origin/feature/user-auth

cd ../review/pr-456
npm install
npm test
npm run dev

# Review code, test functionality
# When done, remove worktree
cd /main-project
git worktree remove ../review/pr-456

使用 Worktree 更新堆叠式 PR

基准 PR 发生变化时，跨 worktree 更新整个链：

# PR-001 got feedback
cd /stack/pr-001
git pull origin feature/001-base-auth
# Make changes, push

# Update PR-002 (in separate worktree)
cd /stack/pr-002
git rebase feature/001-base-auth
git push --force-with-lease origin feature/002-user-profile

# Update PR-003 (in separate worktree)
cd /stack/pr-003
git rebase feature/002-user-profile
git push --force-with-lease origin feature/003-admin-panel

管理依赖项

共享 node_modules（节省磁盘空间）

选项 1：符号链接

cd /worktrees/feature-auth
ln -s /main-project/node_modules node_modules

选项 2：单独安装

cd /worktrees/feature-auth
npm install  # Independent node_modules

权衡：

• 符号链接：占用较少磁盘空间，但可能发生版本冲突
• 单独安装：占用较多磁盘空间，但可确保相互隔离

最佳实践

1. 命名约定

# Use descriptive, consistent names
git worktree add ../worktrees/feature-authentication feature/authentication
git worktree add ../worktrees/hotfix-security hotfix/security-patch

2. 位置策略

# Keep worktrees outside main repo
/Users/dev/project/              # Main repo (never delete)
/Users/dev/project-worktrees/    # All worktrees here (safe to delete)

3. 清理规范

# When PR merged, remove worktree immediately
git worktree remove path/to/worktree

# Periodically check for stale worktrees
git worktree prune

# Delete merged branches
git branch -d feature/old-branch
git push origin --delete feature/old-branch

4. 每个 Worktree 使用一个分支

❌ WRONG: Switching branches in worktree defeats the purpose
✅ CORRECT: Each worktree permanently on one branch

常用命令

# Create worktree with new branch
git worktree add <path> -b <branch>

# Create worktree from existing branch
git worktree add <path> <branch>

# List all worktrees
git worktree list

# Remove worktree
git worktree remove <path>

# Clean up stale references
git worktree prune

# Move worktree to different location
git worktree move <old-path> <new-path>

故障排除

问题：“fatal: '' is already checked out”

原因： 该分支已在另一个 worktree 中检出

解决方案：

# List worktrees to find where branch is checked out
git worktree list

# Either work in existing worktree or remove it first
git worktree remove <path-to-old-worktree>

问题：磁盘空间不足

解决方案：

• 为 node_modules 使用符号链接
• PR 合并后移除 worktree
• 定期运行 git worktree prune
• 对大型仓库考虑使用 sparse-checkout

问题：使用多个 worktree 时 IDE 容易混淆

解决方案：

• 将每个 worktree 作为独立工作区打开
• 使用 IDE 的多窗口／拆分工作区功能
• 为 worktree 使用描述性名称，方便识别

Agent 指令

将 worktree 设置任务委派给版本控制 Agent 时：

Task: Create worktrees for stacked PR development

Requirements:
- Create 3 worktrees in /project-worktrees/
- Worktree 1: pr-001 with branch feature/001-base-auth
- Worktree 2: pr-002 with branch feature/002-user-profile
- Worktree 3: pr-003 with branch feature/003-admin-panel

Commands:
git worktree add ../project-worktrees/pr-001 -b feature/001-base-auth
git worktree add ../project-worktrees/pr-002 -b feature/002-user-profile
git worktree add ../project-worktrees/pr-003 -b feature/003-admin-panel

Verification: git worktree list should show all 3 worktrees

优势

✅ 无需切换分支： 无需使用 git checkout 即可处理多个分支
✅ 并行运行服务器： 同时运行多个开发环境
✅ 保留状态： 构建产物和 node_modules 按分支分别保留
✅ 更安全地审查： 测试 PR 时不会影响主工作目录
✅ 更快切换上下文： 在不同 worktree 之间切换，无需变基

相关技能

• stacked-prs - 将 worktree 与堆叠式 PR 工作流结合使用
• git-workflow - 通用 Git 分支模式
• code-review - 在隔离的 worktree 中审查代码