git-worktrees

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Git Worktrees

Git Worktree

Overview

概述

Git worktrees allow you to have multiple working directories from the same repository, each with a different branch checked out. Work on multiple branches simultaneously without switching.

Git Worktree允许你从同一个仓库拥有多个工作目录，每个目录对应一个已检出的不同分支。无需切换分支即可同时在多个分支上工作。

When to Use Worktrees

适用场景

✅ Perfect For:

✅ 最佳适用场景：

Stacked PR development (one worktree per PR)
Urgent hotfix while working on feature
Parallel development on multiple features
Code review in isolation
Testing cross-branch interactions
Running multiple dev servers simultaneously

堆叠PR开发（每个PR对应一个worktree）
开发功能时处理紧急修复
同时开发多个功能
隔离环境下的代码评审
测试跨分支交互
同时运行多个开发服务器

⚠️ Consider Alternatives When:

⚠️ 考虑替代方案的场景：

Limited disk space (worktrees duplicate working directory)
Simple branch switching is sufficient
Only working on one branch at a time

磁盘空间有限（worktree会复制工作目录）
简单的分支切换即可满足需求
同一时间仅在一个分支上工作

Basic Workflow

基础工作流

Create Worktree

创建Worktree

New Branch:

bash

undefined

新分支：

bash

undefined

Create worktree with new branch

创建带有新分支的worktree

git worktree add ../worktrees/feature-auth -b feature/authentication

Navigate to worktree

进入worktree目录

cd ../worktrees/feature-auth


**Existing Branch:**
```bash

cd ../worktrees/feature-auth


**已有分支：**
```bash

Create worktree from existing remote branch

从现有远程分支创建worktree

git worktree add ../worktrees/feature-profile feature/user-profile

Or from origin

或者从origin创建

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

undefined

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

undefined

List Worktrees

列出Worktree

bash

git worktree list

bash

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]

undefined

undefined

Remove Worktree

删除Worktree

bash

undefined

bash

undefined

Remove worktree (deletes directory)

删除worktree（同时删除目录）

git worktree remove ../worktrees/feature-auth

Or manually delete directory and prune

或者手动删除目录后清理引用

rm -rf ../worktrees/feature-auth git worktree prune

undefined

rm -rf ../worktrees/feature-auth git worktree prune

undefined

Directory Structure

目录结构

Recommended layout:

/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

推荐布局：

/Users/dev/
├── my-project/              # 主仓库
│   ├── .git/               # Git数据库
│   ├── src/
│   └── ...
└── my-project-worktrees/    # 所有worktree存放目录
    ├── feature-auth/       # feature/authentication分支
    ├── feature-profile/    # feature/user-profile分支
    ├── hotfix-urgent/      # hotfix/urgent-fix分支
    └── review-pr-123/      # 评审PR #123

Use Case: Stacked PRs

用例：堆叠PR

Perfect for stacked PR workflow - one worktree per PR:

bash

undefined

非常适合堆叠PR工作流——每个PR对应一个worktree：

bash

undefined

Create worktree for each PR in stack

为堆叠中的每个PR创建worktree

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

在每个worktree中独立工作

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

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

已处于feature/002-user-profile分支

Implement user profile (depends on pr-001)

实现用户档案功能（依赖pr-001）

git commit -am "feat: user profile with auth" git push -u origin feature/002-user-profile

cd ../stack/pr-003

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)

实现管理员面板（依赖pr-002）

git commit -am "feat: admin panel" git push -u origin feature/003-admin-panel

undefined

git commit -am "feat: admin panel" git push -u origin feature/003-admin-panel

undefined

Use Case: Parallel Development

用例：并行开发

Run multiple dev servers simultaneously:

bash

undefined

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

bash

undefined

Terminal 1: Main feature development

终端1：主功能开发

cd /project-worktrees/feature-new-ui npm install npm run dev # Server on port 3000

cd /project-worktrees/feature-new-ui npm install npm run dev # 服务器运行在3000端口

Terminal 2: Urgent hotfix (different branch)

终端2：紧急修复（不同分支）

cd /project-worktrees/hotfix-critical npm install npm run dev -- --port 3001 # Server on port 3001

cd /project-worktrees/hotfix-critical npm install npm run dev -- --port 3001 # 服务器运行在3001端口

Both running simultaneously without branch switching

无需切换分支，两个服务同时运行

undefined

undefined

Use Case: Code Review

用例：代码评审

Review PRs in isolation:

bash

undefined

在隔离环境中评审PR：

bash

undefined

Create worktree for PR review

为PR评审创建worktree

git worktree add ../review/pr-456 origin/feature/user-auth

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

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

完成后删除worktree

cd /main-project git worktree remove ../review/pr-456

undefined

cd /main-project git worktree remove ../review/pr-456

undefined

Updating Stacked PRs with Worktrees

使用Worktree更新堆叠PR

When base PR changes, update chain across worktrees:

bash

undefined

当基础PR变更时，更新整个堆叠中的PR：

bash

undefined

PR-001 got feedback

PR-001收到反馈

cd /stack/pr-001 git pull origin feature/001-base-auth

Make changes, push

做出修改并推送

Update PR-002 (in separate worktree)

更新PR-002（在独立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)

更新PR-003（在独立worktree中）

cd /stack/pr-003 git rebase feature/002-user-profile git push --force-with-lease origin feature/003-admin-panel

undefined

cd /stack/pr-003 git rebase feature/002-user-profile git push --force-with-lease origin feature/003-admin-panel

undefined

Managing Dependencies

依赖管理

Shared node_modules (Save Disk Space)

共享node_modules（节省磁盘空间）

Option 1: Symlink

bash

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

Option 2: Separate Install

bash

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

Trade-off:

Symlink: Less disk space, may have version conflicts
Separate: More disk space, guaranteed isolation

方案1：创建符号链接

bash

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

方案2：独立安装

bash

cd /worktrees/feature-auth
npm install  # 独立的node_modules

权衡点：

符号链接：占用更少磁盘空间，可能存在版本冲突
独立安装：占用更多磁盘空间，保证环境隔离

Best Practices

最佳实践

1. Naming Convention

1. 命名规范

bash

undefined

bash

undefined

Use descriptive, consistent names

使用清晰、一致的命名

git worktree add ../worktrees/feature-authentication feature/authentication git worktree add ../worktrees/hotfix-security hotfix/security-patch

undefined

git worktree add ../worktrees/feature-authentication feature/authentication git worktree add ../worktrees/hotfix-security hotfix/security-patch

undefined

2. Location Strategy

2. 存放策略

bash

undefined

bash

undefined

Keep worktrees outside main repo

将worktree放在主仓库外部

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

undefined

/Users/dev/project/ # 主仓库（切勿删除） /Users/dev/project-worktrees/ # 所有worktree存放于此（可安全删除）

undefined

3. Cleanup Discipline

3. 清理规范

bash

undefined

bash

undefined

When PR merged, remove worktree immediately

PR合并后立即删除对应的worktree

git worktree remove path/to/worktree

Periodically check for stale worktrees

定期检查并清理过期的worktree引用

git worktree prune

Delete merged branches

删除已合并的分支

git branch -d feature/old-branch git push origin --delete feature/old-branch

undefined

git branch -d feature/old-branch git push origin --delete feature/old-branch

undefined

4. One Branch Per Worktree

4. 一个Worktree对应一个分支

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

❌ 错误：在worktree中切换分支会失去其存在意义
✅ 正确：每个worktree固定对应一个分支

Common Commands

常用命令

bash

undefined

bash

undefined

Create worktree with new branch

创建带有新分支的worktree

git worktree add <path> -b <branch>

Create worktree from existing branch

从已有分支创建worktree

git worktree add <path> <branch>

List all worktrees

列出所有worktree

git worktree list

Remove worktree

删除worktree

git worktree remove <path>

Clean up stale references

清理过期引用

git worktree prune

Move worktree to different location

移动worktree到其他位置

git worktree move <old-path> <new-path>

undefined

git worktree move <old-path> <new-path>

undefined

Troubleshooting

故障排除

Issue: "fatal: '<branch>' is already checked out"

问题："fatal: '<branch>' is already checked out"

Cause: Branch is checked out in another worktree

Solution:

bash

undefined

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

解决方案：

bash

undefined

List worktrees to find where branch is checked out

列出所有worktree，找到该分支所在位置

git worktree list

Either work in existing worktree or remove it first

要么在已有的worktree中工作，要么先删除它

git worktree remove <path-to-old-worktree>

undefined

git worktree remove <path-to-old-worktree>

undefined

Issue: Disk space concerns

问题：磁盘空间不足

Solution:

Use symlinks for node_modules
Remove worktrees when PRs merged
Run
```
git worktree prune
```
regularly
Consider using sparse-checkout for large repos

解决方案：

为node_modules创建符号链接
PR合并后立即删除对应的worktree
定期运行
```
git worktree prune
```
大型仓库可考虑使用sparse-checkout

Issue: IDE confusion with multiple worktrees

问题：IDE对多个worktree识别混乱

Solution:

Open each worktree as separate workspace
Use IDE's multi-window/split-workspace features
Name worktrees descriptively for easy identification

解决方案：

将每个worktree作为独立工作区打开
使用IDE的多窗口/拆分工作区功能
为worktree设置清晰的名称以便识别

Agent Instructions

Agent指令

When delegating worktree setup to version-control 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

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

任务：为堆叠PR开发创建worktree

需求：
- 在/project-worktrees/目录下创建3个worktree
- Worktree 1：pr-001，对应分支feature/001-base-auth
- Worktree 2：pr-002，对应分支feature/002-user-profile
- Worktree 3：pr-003，对应分支feature/003-admin-panel

命令：
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

验证：git worktree list应显示所有3个worktree

Benefits

优势

✅ No Branch Switching: Work on multiple branches without

git checkout

✅ Parallel Servers: Run multiple dev environments simultaneously ✅ Preserve State: Build artifacts and node_modules stay per-branch ✅ Safer Reviews: Test PRs without affecting main working directory ✅ Faster Context Switch: Jump between worktrees instead of rebasing

✅ 无需切换分支： 无需使用

git checkout

即可在多个分支上工作 ✅ 并行服务器： 同时运行多个开发环境 ✅ 保留状态： 构建产物和node_modules按分支独立保存 ✅ 更安全的评审： 测试PR时不影响主工作目录 ✅ 更快的上下文切换： 在worktree间跳转，无需变基