git-worktree

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Git Worktree - Parallel Development

Git Worktree - 并行开发

Overview

概述

Git worktrees enable multiple working directories from a single repository. Each worktree has its own branch while sharing the same Git object database.

Core principle: Check worktree status, create worktree for parallel work, reference cleanup commands as needed.

Git Worktree 允许从单个仓库创建多个工作目录。每个工作树拥有独立的分支，同时共享同一个Git对象数据库。

核心原则： 检查工作树状态，创建工作树以进行并行工作，按需参考清理命令。

When to Use

适用场景

Use worktrees when:

Working on multiple branches simultaneously
Emergency hotfix needed without disrupting current work
Reviewing PRs in isolation
Testing across branches without stashing

Avoid when:

Quick branch switch (use
```
git switch
```
instead)
Single feature, single branch workflow

适合使用工作树的场景：

同时处理多个分支
需要紧急热修复且不中断当前工作
在隔离环境下评审PR
无需暂存即可跨分支测试

避免使用的场景：

快速切换分支（改用
```
git switch
```
）
单功能单分支的工作流

The Workflow

工作流程

Step 1: Check Worktree Status

步骤1：检查工作树状态

Before creating a worktree, check what already exists:

bash

undefined

创建工作树前，先查看已有的工作树：

bash

undefined

List all worktrees

列出所有工作树

git worktree list

Verbose output with branch info

显示包含分支信息的详细输出

git worktree list --verbose

undefined

git worktree list --verbose

undefined

Step 2: Create Worktree

步骤2：创建工作树

Basic creation:

bash

undefined

基础创建方式：

bash

undefined

Create worktree with new branch from HEAD

从HEAD创建带新分支的工作树

git worktree add ../project-feature-name -b feature-name

Create from specific base branch

从指定基础分支创建工作树

git worktree add ../project-hotfix -b hotfix-critical origin/main

Create from existing remote branch

从已有的远程分支创建工作树

git worktree add ../project-review pr-123


**Tip:** Place worktrees outside the repo directory (e.g., `../project-feature-name`) so they aren't tracked by Git.

**Recommended configuration (run once):**
```bash
git config worktree.guessRemote true
git config worktree.useRelativePaths true  # Requires Git 2.45+

git worktree add ../project-review pr-123


**提示：** 将工作树放在仓库目录外（例如 `../project-feature-name`），避免被Git追踪。

**推荐配置（只需运行一次）：**
```bash
git config worktree.guessRemote true
git config worktree.useRelativePaths true  # 要求Git 2.45+

Step 3: Work in Worktree

步骤3：在工作树中开展工作

Navigate to the worktree and work normally:

bash

cd ../project-feature-name

导航到工作树目录，正常进行开发：

bash

cd ../project-feature-name

Install dependencies, run tests, start Claude, etc.

安装依赖、运行测试、启动Claude等

undefined

undefined

Worktree Management Reference

工作树管理参考

These commands are available for managing worktrees. Surface these to the user when relevant:

List worktrees:

bash

undefined

以下命令可用于管理工作树，在相关场景下可提供给用户：

列出工作树：

bash

undefined

List all worktrees

列出所有工作树

git worktree list

Verbose output with branch and commit info

显示包含分支和提交信息的详细输出

git worktree list --verbose


**Remove worktrees:**
```bash

git worktree list --verbose


**删除工作树：**
```bash

Remove a worktree (must have no uncommitted changes)

删除工作树（必须无未提交的更改）

git worktree remove ../project-feature-name

Force remove (discards uncommitted changes)

强制删除（丢弃未提交的更改）

git worktree remove -f ../project-feature-name


**Prune stale worktrees:**
```bash

git worktree remove -f ../project-feature-name


**清理过期工作树：**
```bash

Clean up metadata for manually deleted worktrees

清理手动删除的工作树的元数据

git worktree prune

Dry run to see what would be pruned

模拟清理，查看会被删除的内容

git worktree prune -n

Repair a disconnected worktree

修复断开连接的工作树

git worktree repair ../project-feature-name

undefined

git worktree repair ../project-feature-name

undefined

Troubleshooting

故障排除

"Another worktree already uses this branch"

Cause: Can't checkout same branch in multiple worktrees.

Solution:

bash

undefined

原因： 无法在多个工作树中检出同一个分支。

解决方案：

bash

undefined

Check which worktree has it

查看哪个工作树正在使用该分支

git worktree list | grep branch-name

Create new branch from same base instead

从相同基础创建新分支替代

git worktree add ../new-path -b branch-copy origin/branch-name

undefined

git worktree add ../new-path -b branch-copy origin/branch-name

undefined

"Worktree contains modified or untracked files"

Cause: Can't remove worktree with uncommitted changes.

Solution:

bash

undefined

原因： 无法删除包含未提交更改的工作树。

解决方案：

bash

undefined

Commit or stash changes first

先提交或暂存更改

cd ../project-feature-name git add . && git commit -m "Final changes"

Or force remove (discards changes)

或强制删除（丢弃更改）

git worktree remove -f ../project-feature-name

undefined

git worktree remove -f ../project-feature-name

undefined

Stale Worktree References

过期工作树引用

Cause: Manually deleted worktree directory without

git worktree remove

Solution:

bash

undefined

原因： 未使用

git worktree remove

就手动删除了工作树目录。

解决方案：

bash

undefined

List worktrees (shows "prunable" entries)

列出工作树（显示可清理的条目）

git worktree list --verbose

Clean up stale metadata

清理过期元数据

git worktree prune

undefined

git worktree prune

undefined

Examples

示例

Example 1: Create worktree for new feature

示例1：为新功能创建工作树

<Good> ```bash

<正确示范>

bash

undefined

Always check existing worktrees first

先检查现有工作树

git worktree list

Create worktree with descriptive branch name

创建带描述性分支名的工作树

git worktree add ../myproject-auth -b feature/auth cd ../myproject-auth

Install dependencies and verify setup

安装依赖并验证环境

npm install npm test


**Why this is good:** Checks existing worktrees, uses descriptive naming, verifies setup before work.
</Good>

<Bad>
```bash

npm install npm test


**优势：** 检查现有工作树，使用清晰的命名，在开发前验证环境。
</正确示范>

<错误示范>
```bash

Create worktree without checking existing ones

未检查现有工作树就创建

git worktree add ../temp -b temp cd ../temp


**Why this is bad:** No verification of existing worktrees, vague naming makes tracking difficult, no setup verification.
</Bad>

git worktree add ../temp -b temp cd ../temp


**问题：** 未验证现有工作树，模糊命名导致难以追踪，未验证环境。
</错误示范>

Example 2: Emergency hotfix pattern

示例2：紧急热修复流程

<Good> ```bash

<正确示范>

bash

undefined

Create hotfix from main, not current branch

从main分支创建热修复，而非当前功能分支

git worktree add ../myproject-hotfix -b hotfix/payment-bug origin/main cd ../myproject-hotfix

Fix bug, test, commit

修复bug、测试、提交

npm test git add . git commit -m "Fix payment processor race condition" git push -u origin hotfix/payment-bug

Return to original work

返回原工作目录

cd ../myproject git worktree remove ../myproject-hotfix


**Why this is good:** Branches from correct base (main), tests before committing, cleans up after.
</Good>

<Bad>
```bash

git worktree remove ../myproject-hotfix


**优势：** 从正确的基础分支（main）创建，提交前测试，完成后清理。
</正确示范>

<错误示范>
```bash

Create hotfix from current feature branch

从当前功能分支创建热修复

git worktree add ../fix -b fix cd ../fix

Make changes, forget to clean up

更改后忘记清理


**Why this is bad:** Wrong base branch (includes feature work), vague naming, no cleanup.
</Bad>


**问题：** 基础分支错误（包含功能开发内容），命名模糊，未清理工作树。
</错误示范>

Example 3: Review PR without switching

示例3：不切换分支评审PR

<Good> ```bash

<正确示范>

bash

undefined

Fetch PR and create read-only worktree

拉取PR并创建只读工作树

git fetch origin pull/123/head:pr-123 git worktree add ../myproject-pr-123 pr-123 cd ../myproject-pr-123

Review and test

评审并测试

npm install npm test

Leave comments, then clean up

留下评论后清理

cd ../myproject git worktree remove ../myproject-pr-123


**Why this is good:** Fetches PR properly, uses PR number in path, cleans up after review.
</Good>

<Bad>
```bash

cd ../myproject git worktree remove ../myproject-pr-123


**优势：** 正确拉取PR，路径中使用PR编号，评审后清理工作树。
</正确示范>

<错误示范>
```bash

Try to checkout PR in main worktree

尝试在主工作树中检出PR

git checkout pr-123 # Loses current work


**Why this is bad:** Switches branch in main worktree, loses current state, forces stashing.
</Bad>

git checkout pr-123 # 丢失当前工作内容


**问题：** 在主工作树中切换分支，丢失当前状态，必须暂存工作内容。
</错误示范>

Integration

集成方案

This skill enables:

Working on multiple branches simultaneously without context switching
Running parallel Claude Code sessions (one per worktree)
Emergency hotfixes without disrupting feature work
Safe PR review in isolated environments

Pairs with:

track-session - Create separate SESSION_PROGRESS.md in each worktree to track independent progress
commit workflows - Each worktree has its own staging area and commits independently
Parallel Claude sessions - Name each Claude session after its worktree branch for clarity

Integration pattern with track-session:

bash

undefined

此技能支持：

同时处理多个分支，无需上下文切换
运行并行的Claude Code会话（每个工作树一个）
紧急热修复且不中断功能开发
在隔离环境中安全评审PR

搭配使用的技能：

track-session - 在每个工作树中创建独立的SESSION_PROGRESS.md，追踪各自的进度
commit workflows - 每个工作树拥有独立的暂存区和提交记录
Parallel Claude sessions - 为每个Claude会话命名，对应其工作树分支，便于区分

与track-session的集成模式：

bash

undefined

Create worktree

创建工作树

git worktree add ../myproject-feature -b feature/new-api cd ../myproject-feature

Create independent progress tracking

创建独立的进度追踪文件

echo "# Session Progress - New API Feature" > SESSION_PROGRESS.md

Start Claude session named "myproject - New API Feature"

启动名为「myproject - New API Feature」的Claude会话

Work proceeds with independent progress tracking

独立追踪开发进度


**Multi-worktree workflow:**
```bash


**多工作树工作流：**
```bash

Terminal 1: Feature work in main worktree

终端1：主工作树中开发功能

cd ~/myproject

Claude session: "myproject - main"

Claude会话：「myproject - main」

Terminal 2: Hotfix in separate worktree

终端2：独立工作树中处理热修复

cd ~/myproject-hotfix

Claude session: "myproject - hotfix"

Claude会话：「myproject - hotfix」

Terminal 3: PR review in separate worktree

终端3：独立工作树中评审PR

cd ~/myproject-pr-123

Claude session: "myproject - PR review"

Claude会话：「myproject - PR review」


**Best practices:**
- Name Claude sessions to match worktree purpose
- Each worktree tracks progress independently
- Use `git worktree list` to see all active work
- Clean up worktrees when branches are merged


**最佳实践：**
- 为Claude会话命名，与工作树用途匹配
- 每个工作树独立追踪进度
- 使用 `git worktree list` 查看所有活跃工作树
- 分支合并后及时清理工作树