Back to Details

git-worktree

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Git Worktree Manager

Git Worktree 管理器

This skill provides a unified interface for managing Git worktrees across your development workflow. Whether you're reviewing PRs in isolation or working on features in parallel, this skill handles all the complexity.
该Skill为开发工作流中的Git工作树管理提供了统一界面。无论你是在隔离环境中评审PR，还是并行开发多个功能，该Skill都能处理所有复杂操作。

What This Skill Does

该Skill的功能

  • Create worktrees from main branch with clear branch names
  • List worktrees with current status
  • Switch between worktrees for parallel work
  • Clean up completed worktrees automatically
  • Interactive confirmations at each step
  • Automatic .gitignore management for worktree directory
  • Automatic .env file copying from main repo to new worktrees
  • 创建工作树：基于主分支创建，使用清晰的分支名称
  • 列出工作树：展示当前状态
  • 切换工作树：支持并行工作
  • 自动清理完成的工作树
  • 每步操作均有交互式确认
  • 自动管理工作树目录的.gitignore
  • 自动将主仓库的.env文件复制到新工作树

CRITICAL: Always Use the Manager Script

重要提示：始终使用管理器脚本

NEVER call 
git worktree add
directly. Always use the 
worktree-manager.sh
script.
The script handles critical setup that raw git commands don't:
  1. Copies 
    .env
    , 
    .env.local
    , 
    .env.test
    , etc. from main repo
  2. Ensures 
    .worktrees
    is in 
    .gitignore
  3. Creates consistent directory structure
bash
undefined
切勿直接调用
git worktree add
命令，请始终使用
worktree-manager.sh
脚本。
该脚本会处理原生Git命令无法完成的关键设置：
  1. 从主仓库复制
    .env
    、
    .env.local
    、
    .env.test
    等文件
  2. 确保
    .worktrees
    目录被添加到
    .gitignore
  3. 创建一致的目录结构
bash
undefined

✅ CORRECT - Always use the script

✅ 正确方式 - 始终使用脚本

bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create feature-name
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create feature-name

❌ WRONG - Never do this directly

❌ 错误方式 - 切勿直接执行此命令

git worktree add .worktrees/feature-name -b feature-name main
undefined
git worktree add .worktrees/feature-name -b feature-name main
undefined

When to Use This Skill

使用场景

Use this skill in these scenarios:
  1. Code Review (
    /workflows:review
    )    : If NOT already on the target branch (PR branch or requested branch), offer worktree for isolated review
  2. Feature Work (
    /workflows:work
    )    : Always ask if user wants parallel worktree or live branch work
  3. Parallel Development: When working on multiple features simultaneously
  4. Cleanup: After completing work in a worktree
在以下场景中使用该Skill：
  1. 代码评审（
    /workflows:review
    ）    ：如果当前不在目标分支（PR分支或指定分支），则提供隔离的工作树用于评审
  2. 功能开发（
    /workflows:work
    ）    ：始终询问用户是要使用并行工作树还是直接在当前分支开发
  3. 并行开发：同时开发多个功能时
  4. 清理操作：完成工作树中的任务后

How to Use

使用方法

In Claude Code Workflows

在Claude Code工作流中使用

The skill is automatically called from 
/workflows:review
and 
/workflows:work
commands:
undefined
该Skill会被
/workflows:review
和
/workflows:work
命令自动调用：
undefined

For review: offers worktree if not on PR branch

评审场景：如果不在PR分支，会提供工作树选项

For work: always asks - new branch or worktree?

开发场景：始终询问 - 新建分支还是使用工作树？

undefined
undefined

Manual Usage

手动使用

You can also invoke the skill directly from bash:
bash
undefined
你也可以直接通过bash调用该Skill：
bash
undefined

Create a new worktree (copies .env files automatically)

创建新工作树（自动复制.env文件）

bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create feature-login
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create feature-login

List all worktrees

列出所有工作树

bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh list
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh list

Switch to a worktree

切换到指定工作树

bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh switch feature-login
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh switch feature-login

Copy .env files to an existing worktree (if they weren't copied)

为已存在的工作树复制.env文件（如果之前未复制）

bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh copy-env feature-login
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh copy-env feature-login

Clean up completed worktrees

清理闲置工作树

bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh cleanup
undefined
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh cleanup
undefined

Commands

命令说明

create <branch-name> [from-branch]

create <branch-name> [from-branch]

Creates a new worktree with the given branch name.
Options:
  • branch-name
    (required): The name for the new branch and worktree
  • from-branch
    (optional): Base branch to create from (defaults to 
    main
    )
Example:
bash
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create feature-login
What happens:
  1. Checks if worktree already exists
  2. Updates the base branch from remote
  3. Creates new worktree and branch
  4. Copies all .env files from main repo (.env, .env.local, .env.test, etc.)
  5. Shows path for cd-ing to the worktree
创建带有指定分支名称的新工作树。
选项：
  • branch-name
    （必填）：新分支和工作树的名称
  • from-branch
    （可选）：创建工作树的基础分支（默认值为
    main
    ）
示例：
bash
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create feature-login
执行流程：
  1. 检查工作树是否已存在
  2. 从远程仓库更新基础分支
  3. 创建新工作树和分支
  4. 从主仓库复制所有.env文件（.env、.env.local、.env.test等）
  5. 显示进入工作树的路径

list
or 
ls

list
或 
ls

Lists all available worktrees with their branches and current status.
Example:
bash
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh list
Output shows:
  • Worktree name
  • Branch name
  • Which is current (marked with ✓)
  • Main repo status
列出所有可用工作树及其分支和当前状态。
示例：
bash
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh list
输出内容：
  • 工作树名称
  • 分支名称
  • 当前活跃的工作树（标记为✓）
  • 主仓库状态

switch <name>
or 
go <name>

switch <name>
或 
go <name>

Switches to an existing worktree and cd's into it.
Example:
bash
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh switch feature-login
Optional:
  • If name not provided, lists available worktrees and prompts for selection
切换到已存在的工作树并进入该目录。
示例：
bash
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh switch feature-login
可选操作：
  • 如果未指定名称，会列出可用工作树并提示选择

cleanup
or 
clean

cleanup
或 
clean

Interactively cleans up inactive worktrees with confirmation.
Example:
bash
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh cleanup
What happens:
  1. Lists all inactive worktrees
  2. Asks for confirmation
  3. Removes selected worktrees
  4. Cleans up empty directories
交互式清理闲置工作树，需确认操作。
示例：
bash
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh cleanup
执行流程：
  1. 列出所有闲置工作树
  2. 请求确认
  3. 删除选中的工作树
  4. 清理空目录

Workflow Examples

工作流示例

Code Review with Worktree

使用工作树进行代码评审

bash
undefined
bash
undefined

Claude Code recognizes you're not on the PR branch

Claude Code检测到你不在PR分支

Offers: "Use worktree for isolated review? (y/n)"

提示："是否使用工作树进行隔离评审？(y/n)"

You respond: yes

你回复：yes

Script runs (copies .env files automatically):

脚本自动执行（自动复制.env文件）：

bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create pr-123-feature-name
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create pr-123-feature-name

You're now in isolated worktree for review with all env vars

现在你处于用于评审的隔离工作树中，包含所有环境变量

cd .worktrees/pr-123-feature-name
cd .worktrees/pr-123-feature-name

After review, return to main:

评审完成后，返回主仓库并清理：

cd ../.. bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh cleanup
undefined
cd ../.. bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh cleanup
undefined

Parallel Feature Development

并行功能开发

bash
undefined
bash
undefined

For first feature (copies .env files):

开发第一个功能（自动复制.env文件）：

bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create feature-login
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create feature-login

Later, start second feature (also copies .env files):

之后开始开发第二个功能（同样自动复制.env文件）：

bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create feature-notifications
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create feature-notifications

List what you have:

列出所有工作树：

bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh list
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh list

Switch between them as needed:

根据需要切换工作树：

bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh switch feature-login
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh switch feature-login

Return to main and cleanup when done:

完成后返回主仓库并清理：

cd . bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh cleanup
undefined
cd . bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh cleanup
undefined

Key Design Principles

核心设计原则

KISS (Keep It Simple, Stupid)

KISS（保持简单）

  • One manager script handles all worktree operations
  • Simple commands with sensible defaults
  • Interactive prompts prevent accidental operations
  • Clear naming using branch names directly
  • 单一管理器脚本处理所有工作树操作
  • 简单命令搭配合理默认值
  • 交互式提示防止误操作
  • 清晰命名直接使用分支名称

Opinionated Defaults

预设默认规则

  • Worktrees always created from main (unless specified)
  • Worktrees stored in .worktrees/ directory
  • Branch name becomes worktree name
  • .gitignore automatically managed
  • 工作树默认从main分支创建（可指定其他分支）
  • 工作树存储在**.worktrees/**目录
  • 分支名称即为工作树名称
  • .gitignore自动管理

Safety First

安全优先

  • Confirms before creating worktrees
  • Confirms before cleanup to prevent accidental removal
  • Won't remove current worktree
  • Clear error messages for issues
  • 创建前确认
  • 清理前确认防止误删
  • 不会删除当前活跃的工作树
  • 出现问题时显示清晰的错误信息

Integration with Workflows

与工作流的集成

/workflows:review

/workflows:review

Instead of always creating a worktree:
1. Check current branch
2. If ALREADY on target branch (PR branch or requested branch) → stay there, no worktree needed
3. If DIFFERENT branch than the review target → offer worktree:
   "Use worktree for isolated review? (y/n)"
   - yes → call git-worktree skill
   - no → proceed with PR diff on current branch
并非始终创建工作树：
1. 检查当前分支
2. 如果**已在目标分支**（PR分支或指定分支）→ 无需工作树，直接进行评审
3. 如果**当前分支与评审目标分支不同**→ 提供工作树选项：
   "是否使用工作树进行隔离评审？(y/n)"
   - yes → 调用git-worktree skill
   - no → 在当前分支查看PR差异

/workflows:work

/workflows:work

Always offer choice:
1. Ask: "How do you want to work?
   1. New branch on current worktree (live work)
   2. Worktree (parallel work)"

2. If choice 1 → create new branch normally
3. If choice 2 → call git-worktree skill to create from main
始终提供选择：
1. 询问："你希望如何开发？
   1. 在当前工作树创建新分支（实时开发）
   2. 使用工作树（并行开发）"

2. 如果选择1 → 正常创建新分支
3. 如果选择2 → 调用git-worktree skill从main分支创建工作树

Troubleshooting

故障排除

"Worktree already exists"

"Worktree already exists"

If you see this, the script will ask if you want to switch to it instead.
出现此提示时，脚本会询问你是否要切换到已存在的工作树。

"Cannot remove worktree: it is the current worktree"

"Cannot remove worktree: it is the current worktree"

Switch out of the worktree first (to main repo), then cleanup:
bash
cd $(git rev-parse --show-toplevel)
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh cleanup
先切换到主仓库，再执行清理操作：
bash
cd $(git rev-parse --show-toplevel)
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh cleanup

Lost in a worktree?

不知道当前处于哪个工作树？

See where you are:
bash
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh list
查看当前所有工作树状态：
bash
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh list

.env files missing in worktree?

工作树中缺少.env文件？

If a worktree was created without .env files (e.g., via raw 
git worktree add
), copy them:
bash
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh copy-env feature-name
Navigate back to main:
bash
cd $(git rev-parse --show-toplevel)
如果工作树是通过原生
git worktree add
命令创建的（未复制.env文件），可执行以下命令复制：
bash
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh copy-env feature-name
返回主仓库：
bash
cd $(git rev-parse --show-toplevel)

Technical Details

技术细节

Directory Structure

目录结构

.worktrees/
├── feature-login/          # Worktree 1
│   ├── .git
│   ├── app/
│   └── ...
├── feature-notifications/  # Worktree 2
│   ├── .git
│   ├── app/
│   └── ...
└── ...

.gitignore (updated to include .worktrees)
.worktrees/
├── feature-login/          # 工作树1
│   ├── .git
│   ├── app/
│   └── ...
├── feature-notifications/  # 工作树2
│   ├── .git
│   ├── app/
│   └── ...
└── ...

.gitignore（已更新为包含.worktrees）

How It Works

工作原理

  • Uses 
    git worktree add
    for isolated environments
  • Each worktree has its own branch
  • Changes in one worktree don't affect others
  • Share git history with main repo
  • Can push from any worktree
  • 使用
    git worktree add
    创建隔离环境
  • 每个工作树对应独立分支
  • 一个工作树中的修改不会影响其他工作树
  • 与主仓库共享Git历史
  • 可从任意工作树推送代码

Performance

性能

  • Worktrees are lightweight (just file system links)
  • No repository duplication
  • Shared git objects for efficiency
  • Much faster than cloning or stashing/switching
  • 工作树轻量（仅为文件系统链接）
  • 无需复制仓库
  • 共享Git对象以提高效率
  • 比克隆或 stash/切换分支快得多