worktrees

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Git Worktrees

Overview

概述

Git worktrees enable checking out multiple branches simultaneously in separate directories, all sharing the same repository. Create a worktree instead of stashing changes or cloning separately.

Core principle: One worktree per active branch. Switch contexts by changing directories, not branches.

Git worktree 允许在独立目录中同时检出多个分支，所有分支共享同一个仓库。无需暂存变更或单独克隆仓库，直接创建worktree即可。

核心原则： 每个活跃分支对应一个worktree。通过切换目录而非切换分支来切换上下文。

Core Concepts

核心概念

Concept	Description
Main worktree	Original working directory from `git clone` or `git init`
Linked worktree	Additional directories created with `git worktree add`
Shared `.git`	All worktrees share same Git object database (no duplication)
Branch lock	Each branch can only be checked out in ONE worktree at a time
Worktree metadata	Administrative files in `.git/worktrees/` tracking linked worktrees

概念	描述
主工作目录（Main worktree）	通过 `git clone` 或 `git init` 创建的原始工作目录
关联工作目录（Linked worktree）	使用 `git worktree add` 创建的额外目录
共享.git目录（Shared `.git` ）	所有worktree共享同一个Git对象数据库（无重复存储）
分支锁定（Branch lock）	每个分支同一时间仅能在一个worktree中检出
Worktree元数据	存储在 `.git/worktrees/` 中的管理文件，用于跟踪关联工作目录

Quick Reference

速查指南

Task	Command
Create worktree (existing branch)	`git worktree add <path> <branch>`
Create worktree (new branch)	`git worktree add -b <branch> <path>`
Create worktree (new branch from ref)	`git worktree add -b <branch> <path> <start>`
Create detached worktree	`git worktree add --detach <path> <commit>`
List all worktrees	`git worktree list`
Remove worktree	`git worktree remove <path>`
Force remove worktree	`git worktree remove --force <path>`
Move worktree	`git worktree move <old> <new>`
Lock worktree	`git worktree lock <path>`
Unlock worktree	`git worktree unlock <path>`
Prune stale worktrees	`git worktree prune`
Repair worktree links	`git worktree repair`
Compare files between worktrees	`diff ../worktree-a/file ../worktree-b/file`
Get one file from another branch	`git checkout <branch> -- <path>`
Get partial file changes	`git checkout -p <branch> -- <path>`
Cherry-pick a commit	`git cherry-pick <commit>`
Cherry-pick without committing	`git cherry-pick --no-commit <commit>`
Merge without auto-commit	`git merge --no-commit <branch>`

任务	命令
创建worktree（基于已有分支）	`git worktree add <path> <branch>`
创建worktree（基于新分支）	`git worktree add -b <branch> <path>`
创建worktree（基于引用创建新分支）	`git worktree add -b <branch> <path> <start>`
创建分离头指针的worktree	`git worktree add --detach <path> <commit>`
列出所有worktree	`git worktree list`
删除worktree	`git worktree remove <path>`
强制删除worktree	`git worktree remove --force <path>`
移动worktree	`git worktree move <old> <new>`
锁定worktree	`git worktree lock <path>`
解锁worktree	`git worktree unlock <path>`
清理过期worktree	`git worktree prune`
修复worktree链接	`git worktree repair`
对比不同worktree的文件	`diff ../worktree-a/file ../worktree-b/file`
从其他分支获取单个文件	`git checkout <branch> -- <path>`
获取文件的部分变更	`git checkout -p <branch> -- <path>`
拣选提交	`git cherry-pick <commit>`
拣选提交但不自动提交	`git cherry-pick --no-commit <commit>`
合并但不自动提交	`git merge --no-commit <branch>`

Essential Commands

核心命令

Create a Worktree

创建Worktree

bash

undefined

bash

undefined

Create worktree with existing branch

基于已有分支创建worktree

git worktree add ../feature-x feature-x

Create worktree with new branch from current HEAD

基于当前HEAD创建新分支的worktree

git worktree add -b new-feature ../new-feature

Create worktree with new branch from specific commit

基于指定提交创建新分支的worktree

git worktree add -b hotfix-123 ../hotfix origin/main

Create worktree tracking remote branch

创建跟踪远程分支的worktree

git worktree add --track -b feature ../feature origin/feature

Create worktree with detached HEAD (for experiments)

创建分离头指针的worktree（用于实验）

git worktree add --detach ../experiment HEAD~5

undefined

git worktree add --detach ../experiment HEAD~5

undefined

List Worktrees

列出Worktree

bash

undefined

bash

undefined

Simple list

简单列表

git worktree list

Verbose output with additional details

包含额外详情的详细输出

git worktree list -v

Machine-readable format (for scripting)

机器可读格式（用于脚本）

git worktree list --porcelain


**Example output:**

/home/user/project abc1234 [main] /home/user/project-feature def5678 [feature-x] /home/user/project-hotfix ghi9012 [hotfix-123]

undefined

git worktree list --porcelain


**示例输出：**

/home/user/project abc1234 [main] /home/user/project-feature def5678 [feature-x] /home/user/project-hotfix ghi9012 [hotfix-123]

undefined

Remove a Worktree

删除Worktree

bash

undefined

bash

undefined

Remove worktree (working directory must be clean)

删除worktree（工作目录必须干净）

git worktree remove ../feature-x

Force remove (discards uncommitted changes)

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

git worktree remove --force ../feature-x

undefined

git worktree remove --force ../feature-x

undefined

Move a Worktree

移动Worktree

bash

undefined

bash

undefined

Relocate worktree to new path

将worktree迁移到新路径

git worktree move ../old-path ../new-path

undefined

git worktree move ../old-path ../new-path

undefined

Lock/Unlock Worktrees

锁定/解锁Worktree

bash

undefined

bash

undefined

Lock worktree (prevents pruning if on removable storage)

锁定worktree（防止在可移动存储上被清理）

git worktree lock ../feature-x git worktree lock --reason "On USB drive" ../feature-x

Unlock worktree

解锁worktree

git worktree unlock ../feature-x

undefined

git worktree unlock ../feature-x

undefined

Prune Stale Worktrees

清理过期Worktree

bash

undefined

bash

undefined

Remove stale worktree metadata (after manual directory deletion)

移除过期的worktree元数据（手动删除目录后执行）

git worktree prune

Dry-run to see what would be pruned

预演清理操作，查看会被清理的内容

git worktree prune --dry-run

Verbose output

详细输出

git worktree prune -v

undefined

git worktree prune -v

undefined

Repair Worktrees

修复Worktree

bash

undefined

bash

undefined

Repair worktree links after moving directories manually

手动移动目录后修复worktree链接

git worktree repair

Repair specific worktree

修复指定的worktree

git worktree repair ../feature-x

undefined

git worktree repair ../feature-x

undefined

Workflow Patterns

工作流模式

Pattern 1: Feature + Hotfix in Parallel

模式1：特性开发+热修复并行

To fix a bug while feature work is in progress:

bash

undefined

在进行特性开发的同时修复bug：

bash

undefined

Create worktree for hotfix from main

基于main分支创建热修复worktree

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

Switch to hotfix directory, fix, commit, push

切换到热修复目录，修复bug、提交、推送

cd ../project-hotfix git add . && git commit -m "fix: resolve critical bug #456" git push origin hotfix-456

Return to feature work

返回特性开发工作

cd ../project

Clean up when done

完成后清理

git worktree remove ../project-hotfix

undefined

git worktree remove ../project-hotfix

undefined

Pattern 2: PR Review While Working

模式2：开发时评审PR

To review a PR without affecting current work:

bash

undefined

在不影响当前工作的前提下评审PR：

bash

undefined

Fetch PR branch and create worktree

获取PR分支并创建worktree

git fetch origin pull/123/head:pr-123 git worktree add ../project-review pr-123

Review: run tests, inspect code

评审：运行测试、检查代码

cd ../project-review

Return to work, then clean up

返回工作，然后清理

cd ../project git worktree remove ../project-review git branch -d pr-123

undefined

cd ../project git worktree remove ../project-review git branch -d pr-123

undefined

Pattern 3: Compare Implementations

模式3：对比实现方案

To compare code across branches side-by-side:

bash

undefined

并排对比不同分支的代码：

bash

undefined

Create worktrees for different versions

为不同版本创建worktree

git worktree add ../project-v1 v1.0.0 git worktree add ../project-v2 v2.0.0

Diff, compare, or run both simultaneously

对比、比较或同时运行两个版本

diff ../project-v1/src/module.js ../project-v2/src/module.js

Clean up

清理

git worktree remove ../project-v1 git worktree remove ../project-v2

undefined

git worktree remove ../project-v1 git worktree remove ../project-v2

undefined

Pattern 4: Long-Running Tasks

模式4：长时间运行任务

To run tests/builds in isolation while continuing development:

bash

undefined

在隔离环境中运行测试/构建，同时继续开发：

bash

undefined

Create worktree for CI-like testing

为类CI测试创建worktree

git worktree add ../project-test main

Start long-running tests in background

在后台启动长时间运行的测试

cd ../project-test && npm test &

Continue development in main worktree

在主工作目录继续开发

cd ../project

undefined

cd ../project

undefined

Pattern 5: Stable Reference

模式5：稳定参考分支

To maintain a clean main checkout for reference:

bash

undefined

维护一个干净的main分支检出目录作为参考：

bash

undefined

Create permanent worktree for main branch

为main分支创建永久worktree

git worktree add ../project-main main

Lock to prevent accidental removal

锁定以防止意外删除

git worktree lock --reason "Reference checkout" ../project-main

undefined

git worktree lock --reason "Reference checkout" ../project-main

undefined

Pattern 6: Selective Merging from Multiple Features

模式6：从多个特性分支选择性合并

To combine specific changes from multiple feature branches:

bash

undefined

合并来自多个特性分支的特定变更：

bash

undefined

Create worktrees for each feature to review

为每个特性分支创建worktree以便评审

git worktree add ../project-feature-1 feature-1 git worktree add ../project-feature-2 feature-2

Review changes in each worktree

评审每个worktree中的变更

diff ../project/src/module.js ../project-feature-1/src/module.js diff ../project/src/module.js ../project-feature-2/src/module.js

From main worktree, selectively take changes

在主工作目录中选择性获取变更

cd ../project git checkout feature-1 -- src/moduleA.js src/utils.js git checkout feature-2 -- src/moduleB.js git commit -m "feat: combine selected changes from feature branches"

Or cherry-pick specific commits

或拣选特定提交

git cherry-pick abc1234 # from feature-1 git cherry-pick def5678 # from feature-2

git cherry-pick abc1234 # 来自feature-1 git cherry-pick def5678 # 来自feature-2

Clean up

清理

git worktree remove ../project-feature-1 git worktree remove ../project-feature-2

undefined

git worktree remove ../project-feature-1 git worktree remove ../project-feature-2

undefined

Comparing and Merging Changes Between Worktrees

不同Worktree之间的对比与合并

Since all worktrees share the same Git repository, you can compare files, cherry-pick commits, and selectively merge changes between them.

由于所有worktree共享同一个Git仓库，你可以在它们之间对比文件、拣选提交以及选择性合并变更。

Compare and Review File Changes

对比与评审文件变更

Since worktrees are just directories, you can compare files directly:

bash

undefined

worktree本质上是目录，因此可以直接对比文件：

bash

undefined

Compare specific file between worktrees

对比不同worktree中的特定文件

diff ../project-main/src/app.js ../project-feature/src/app.js

Use git diff to compare branches (works from any worktree)

使用git diff对比分支（可在任意worktree中执行）

git diff main..feature-branch -- src/app.js

Visual diff with your preferred tool

使用你偏好的工具进行可视化对比

code --diff ../project-main/src/app.js ../project-feature/src/app.js

Compare entire directories

对比整个目录

diff -r ../project-v1/src ../project-v2/src

undefined

diff -r ../project-v1/src ../project-v2/src

undefined

Merge Only One File from a Worktree

仅合并单个文件来自某个Worktree

You can selectively bring a single file from another branch using

git checkout

bash

undefined

你可以使用

git checkout

选择性地从其他分支获取单个文件：

bash

undefined

In your current branch, get a specific file from another branch

在当前分支中，从其他分支获取特定文件

git checkout feature-branch -- path/to/file.js

Or get it from a specific commit

或从特定提交获取

git checkout abc1234 -- path/to/file.js

Get multiple specific files

获取多个特定文件

git checkout feature-branch -- src/module.js src/utils.js


For **partial file changes** (specific hunks/lines only):

```bash

git checkout feature-branch -- src/module.js src/utils.js


对于**部分文件变更**（仅特定代码块/行）：

```bash

Interactive patch mode - select which changes to take

交互式补丁模式 - 选择要获取的变更

git checkout -p feature-branch -- path/to/file.js


This prompts you to accept/reject each change hunk individually with options:
- `y` - apply this hunk
- `n` - skip this hunk
- `s` - split into smaller hunks
- `e` - manually edit the hunk

git checkout -p feature-branch -- path/to/file.js


这会提示你逐个接受/拒绝每个变更块，选项包括：
- `y` - 应用此变更块
- `n` - 跳过此变更块
- `s` - 拆分为更小的变更块
- `e` - 手动编辑变更块

Cherry-Pick Commits from Worktrees

从Worktree拣选提交

Cherry-picking works at the commit level. Since all worktrees share the same repository, you can cherry-pick any commit:

bash

undefined

拣选操作基于提交级别。由于所有worktree共享同一个仓库，你可以拣选任意提交：

bash

undefined

Find the commit hash (from any worktree or git log)

查找提交哈希（可在任意worktree或git log中查看）

git log feature-branch --oneline

Cherry-pick specific commit into your current branch

将特定提交拣选到当前分支

git cherry-pick abc1234

Cherry-pick multiple commits

拣选多个提交

git cherry-pick abc1234 def5678

Cherry-pick a range of commits

拣选一个范围内的提交

git cherry-pick abc1234^..def5678

Cherry-pick without committing (stage changes only)

拣选提交但不自动提交（仅暂存变更）

git cherry-pick --no-commit abc1234

undefined

git cherry-pick --no-commit abc1234

undefined

Merge Changes from Multiple Worktrees

从多个Worktree合并变更

You can merge or cherry-pick from multiple branches:

bash

undefined

你可以依次合并多个分支，或同时合并：

bash

undefined

Merge multiple branches sequentially

依次合并多个分支

git merge feature-1 git merge feature-2

Or use octopus merge for multiple branches at once

或使用章鱼合并同时合并多个分支

git merge feature-1 feature-2 feature-3

Cherry-pick commits from multiple branches

从多个分支拣选提交

git cherry-pick abc1234 # from feature-1 git cherry-pick def5678 # from feature-2

undefined

git cherry-pick abc1234 # 来自feature-1 git cherry-pick def5678 # 来自feature-2

undefined

Selective Merging - Pick Which Changes to Include

选择性合并 - 选择要包含的变更

Option 1: Selective File Checkout

选项1：选择性文件检出

bash

undefined

bash

undefined

Get specific files from different branches

从不同分支获取特定文件

git checkout feature-1 -- src/moduleA.js git checkout feature-2 -- src/moduleB.js git commit -m "Merge selected files from feature branches"

undefined

git checkout feature-1 -- src/moduleA.js git checkout feature-2 -- src/moduleB.js git commit -m "Merge selected files from feature branches"

undefined

Option 2: Interactive Patch Selection

选项2：交互式补丁选择

bash

undefined

bash

undefined

Select specific hunks from a file

选择文件中的特定代码块

git checkout -p feature-1 -- src/shared.js

undefined

git checkout -p feature-1 -- src/shared.js

undefined

Option 3: Cherry-Pick with Selective Staging

选项3：拣选并选择性暂存

bash

undefined

bash

undefined

Apply changes without committing

应用变更但不提交

git cherry-pick --no-commit abc1234

Unstage what you don't want

取消暂存不需要的文件

git reset HEAD -- unwanted-file.js git checkout -- unwanted-file.js

Commit only what you kept

仅提交保留的变更

git commit -m "Selected changes from feature-1"

undefined

git commit -m "Selected changes from feature-1"

undefined

Option 4: Merge with Manual Selection

选项4：合并并手动选择

bash

undefined

bash

undefined

Start merge but don't auto-commit

开始合并但不自动提交

git merge --no-commit feature-1

Review and modify staged changes

评审并修改暂存的变更

git status git reset HEAD -- file-to-exclude.js git checkout -- file-to-exclude.js

Commit your selection

提交你的选择

git commit -m "Merge selected changes from feature-1"

undefined

git commit -m "Merge selected changes from feature-1"

undefined

Option 5: Using git restore (Git 2.23+)

选项5：使用git restore（Git 2.23+）

bash

undefined

bash

undefined

Restore specific file from another branch

从其他分支恢复特定文件

git restore --source=feature-branch -- path/to/file.js

Interactive restore with patch selection

交互式恢复并选择补丁

git restore -p --source=feature-branch -- path/to/file.js

undefined

git restore -p --source=feature-branch -- path/to/file.js

undefined

Directory Structure Conventions

目录结构规范

Organize worktrees predictably:

~/projects/
  myproject/              # Main worktree (main/master branch)
  myproject-feature-x/    # Feature branch worktree
  myproject-hotfix/       # Hotfix worktree
  myproject-review/       # Temporary PR review worktree

Naming convention:

<project>-<purpose>

<project>-<branch>

可预测地组织worktree：

~/projects/
  myproject/              # 主工作目录（main/master分支）
  myproject-feature-x/    # 特性分支worktree
  myproject-hotfix/       # 热修复worktree
  myproject-review/       # 临时PR评审worktree

命名规范：

<项目名>-<用途>

或

<项目名>-<分支名>

Best Practices

最佳实践

Practice	Rationale
Use sibling directories	Keep worktrees at same level as main project for easy navigation
Name by purpose	`project-review` is clearer than `project-pr-123`
Clean up promptly	Remove worktrees when done to avoid confusion
Lock remote worktrees	Prevent pruning if worktree is on network/USB storage
Use `--detach` for experiments	Avoid creating throwaway branches
Commit before removing	Always commit or stash before `git worktree remove`

实践	理由
使用同级目录	将worktree与主项目放在同一层级，便于导航
按用途命名	`project-review` 比 `project-pr-123` 更清晰
及时清理	完成任务后立即删除worktree，避免混乱
锁定远程worktree	若worktree位于网络/USB存储，锁定以防止被清理
实验时使用 `--detach`	避免创建临时分支
删除前提交变更	执行 `git worktree remove` 前务必提交或暂存变更

Common Issues and Solutions

常见问题与解决方案

Issue: "Branch is already checked out"

问题："Branch is already checked out"

Cause: Attempting to checkout a branch that's active in another worktree.

Solution:

bash

undefined

原因： 尝试检出已在其他worktree中激活的分支。

解决方案：

bash

undefined

Find where the branch is checked out

查找分支所在的worktree

git worktree list

Either work in that worktree or remove it first

要么在该worktree中操作，要么先删除它

git worktree remove ../other-worktree

undefined

git worktree remove ../other-worktree

undefined

Issue: Stale worktree after manual deletion

问题：手动删除目录后出现过期worktree

Cause: Deleted worktree directory without using

git worktree remove

Solution:

bash

undefined

原因： 未使用

git worktree remove

就删除了worktree目录。

解决方案：

bash

undefined

Clean up stale metadata

清理过期的元数据

git worktree prune

undefined

git worktree prune

undefined

Issue: Worktree moved manually

问题：手动移动了worktree

Cause: Moved worktree directory without using

git worktree move

Solution:

bash

undefined

原因： 未使用

git worktree move

就移动了worktree目录。

解决方案：

bash

undefined

Repair the worktree links

修复worktree链接

git worktree repair

Or specify the new path

或指定新路径

git worktree repair /new/path/to/worktree

undefined

git worktree repair /new/path/to/worktree

undefined

Issue: Worktree on removed drive

问题：worktree所在存储设备已移除

Cause: Worktree was on removable storage that's no longer connected.

Solution:

bash

undefined

原因： worktree位于已断开连接的可移动存储上。

解决方案：

bash

undefined

If temporary, lock it to prevent pruning

若为临时情况，锁定以防止被清理

git worktree lock ../usb-worktree

If permanent, prune it

若为永久移除，清理它

git worktree prune

undefined

git worktree prune

undefined

Common Mistakes

常见错误

Mistake	Fix
Using `rm -rf` to delete worktree	Always use `git worktree remove` , then `git worktree prune` if needed
Forgetting branch is locked to worktree	Run `git worktree list` before checkout errors
Not cleaning up temporary worktrees	Remove worktrees immediately after task completion
Creating worktrees in nested locations	Use sibling directories ( `../project-feature` ) not subdirs
Moving worktree directory manually	Use `git worktree move` or run `git worktree repair` after

错误	修复方法
使用 `rm -rf` 删除worktree	始终使用 `git worktree remove` ，必要时再执行 `git worktree prune`
忘记分支已被worktree锁定	出现检出错误前先运行 `git worktree list`
未清理临时worktree	任务完成后立即删除worktree
在嵌套位置创建worktree	使用同级目录（ `../project-feature` ）而非子目录
手动移动worktree目录	使用 `git worktree move` ，或移动后运行 `git worktree repair`

Agent Workflow Integration

Agent工作流集成

To isolate parallel agent tasks:

bash

undefined

隔离并行Agent任务：

bash

undefined

Create worktree for isolated task

为隔离任务创建worktree

git worktree add -b task-123 ../project-task-123 cd ../project-task-123

Make changes, run tests, return

进行变更、运行测试，然后返回

cd ../project


To experiment safely with detached HEAD:

```bash

cd ../project


安全地使用分离头指针进行实验：

```bash

Create detached worktree (no branch to clean up)

创建分离头指针的worktree（无需清理临时分支）

git worktree add --detach ../project-experiment cd ../project-experiment

Experiment, then discard or commit to new branch

进行实验，然后丢弃或提交到新分支

git worktree remove --force ../project-experiment

undefined

git worktree remove --force ../project-experiment

undefined

Verification Checklist

验证清单

Before using worktrees:

Understand that branches can only be checked out in one worktree
Know where worktrees will be created (use sibling directories)
Plan cleanup strategy for temporary worktrees

When creating worktrees:

Use descriptive directory names
Verify branch is not already checked out elsewhere
Consider using
```
--detach
```
for experiments

When removing worktrees:

Commit or stash any uncommitted changes
Use
```
git worktree remove
```
, not
```
rm -rf
```
Run
```
git worktree prune
```
if directory was deleted manually

使用worktree前：

理解分支同一时间仅能在一个worktree中检出
确定worktree的创建位置（使用同级目录）
规划临时worktree的清理策略

创建worktree时：

使用描述性目录名
验证分支未在其他位置检出
实验时考虑使用
```
--detach
```

删除worktree时：

提交或暂存所有未提交变更
使用
```
git worktree remove
```
而非
```
rm -rf
```
若手动删除了目录，运行
```
git worktree prune
```