Back to Details

git-worktree

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Git Worktree Manager

Git工作树管理器

Manage isolated Git worktrees for parallel development, following project conventions.
遵循项目规范，管理用于并行开发的隔离式Git工作树。

Quick Reference

快速参考

CommandDescription
create <name> [base]
Create worktree with symlinked .env
list
List all worktrees
cleanup
Remove inactive worktrees
switch <name>
Switch to a worktree
命令说明
create <name> [base]
创建带有符号链接.env文件的工作树
list
列出所有工作树
cleanup
移除闲置工作树
switch <name>
切换到指定工作树

CRITICAL: Always Use the Manager Script

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

NEVER call 
git worktree add
directly. Always use the script.
bash
undefined
切勿直接调用
git worktree add
命令。请始终使用本脚本。
bash
undefined

CORRECT

正确方式

bash ~/.claude/skills/git-worktree/scripts/worktree-manager.sh create feature-name
bash ~/.claude/skills/git-worktree/scripts/worktree-manager.sh create feature-name

WRONG - Never do this directly

错误方式 - 切勿直接执行以下命令

git worktree add .github/worktrees/feature-name -b feature-name develop

The script handles:
1. Symlinks `.env` file (not copy) from project root
2. Ensures `.github/worktrees/` is in `.gitignore`
3. Creates consistent directory structure at `.github/worktrees/`
git worktree add .github/worktrees/feature-name -b feature-name develop

本脚本会处理以下事项：
1. 从项目根目录为`.env`文件创建符号链接（而非复制）
2. 确保`.github/worktrees/`已添加到`.gitignore`
3. 在`.github/worktrees/`目录下创建统一的目录结构

CRITICAL: Create the Worktree, Then STOP

重要提示：创建工作树后请立即停止当前会话

After creating a worktree, STOP. Do NOT implement anything in the current session. Do NOT 
cd
into the worktree and keep working.
Your job in this session is ONLY:
  1. Create the worktree
  2. Show the user the copy-paste command from the script output
  3. STOP and tell the user to run that command in a new terminal
All planning, brainstorming, and implementation happens in the new Claude Code instance inside the worktree — NOT here.
Why: Claude Code's working directory and statusline are set at launch time. If you work here after creating a worktree, auto-compact will lose the worktree context and revert to the main repo mid-work.
创建工作树后，请停止当前操作。不要在当前会话中进行任何开发工作，不要
cd
到工作树中继续操作。
你在本次会话中的任务仅为：
  1. 创建工作树
  2. 向用户展示脚本输出中的可复制命令
  3. 停止操作并告知用户在新终端中运行该命令
所有的规划、头脑风暴和开发工作都应在工作树内的新Claude Code实例中进行——而非当前会话。
原因： Claude Code的工作目录和状态行是在启动时设置的。如果在创建工作树后继续在当前会话中操作，自动压缩功能会丢失工作树上下文，中途切换回主仓库。

Project Conventions

项目规范

  • Default base branch: 
    develop
    (not 
    main
    )
  • Symlinks for 
    .env
    files, not copies — single source of truth
  • Worktree directory: 
    .github/worktrees/
  • 默认基准分支：
    develop
    （而非
    main
    ）
  • .env
    文件使用符号链接而非复制——保持唯一可信源
  • 工作树目录：
    .github/worktrees/

Commands

命令说明

create <branch-name> [from-branch]

create <branch-name> [from-branch]

Creates worktree in 
.github/worktrees/<branch-name>
. Defaults to branching from 
develop
.
bash
undefined
在
.github/worktrees/<branch-name>
目录下创建工作树。默认基于
develop
分支创建。
bash
undefined

Create from develop (default)

基于develop分支创建（默认）

bash ~/.claude/skills/git-worktree/scripts/worktree-manager.sh create feature/pipeline-steps
bash ~/.claude/skills/git-worktree/scripts/worktree-manager.sh create feature/pipeline-steps

Create from specific branch

基于指定分支创建

bash ~/.claude/skills/git-worktree/scripts/worktree-manager.sh create hotfix/auth main

**What happens:**
1. Checks if worktree exists
2. Creates `.github/worktrees/` directory if needed
3. Updates base branch from remote
4. Creates worktree and branch
5. **Symlinks `.env` from project root**
6. Verifies symlink
7. **Outputs a copy-paste command** to launch Claude Code in the worktree
bash ~/.claude/skills/git-worktree/scripts/worktree-manager.sh create hotfix/auth main

**执行流程：**
1. 检查工作树是否已存在
2. 若需要则创建`.github/worktrees/`目录
3. 从远程仓库更新基准分支
4. 创建工作树和分支
5. **从项目根目录为.env创建符号链接**
6. 验证符号链接
7. **输出可复制的命令**，用于在工作树中启动Claude Code

list
or 
ls

list
或 
ls

bash
bash ~/.claude/skills/git-worktree/scripts/worktree-manager.sh list
Shows:
  • Worktree name and branch
  • Current worktree marked with 
    *
  • Main repo status
bash
bash ~/.claude/skills/git-worktree/scripts/worktree-manager.sh list
展示内容：
  • 工作树名称和分支
  • 当前工作树标记为
    *
  • 主仓库状态

switch <name>
or 
go <name>

switch <name>
或 
go <name>

bash
bash ~/.claude/skills/git-worktree/scripts/worktree-manager.sh switch feature/pipeline-steps
bash
bash ~/.claude/skills/git-worktree/scripts/worktree-manager.sh switch feature/pipeline-steps

cleanup
or 
clean

cleanup
或 
clean

Removes inactive worktrees interactively.
bash
bash ~/.claude/skills/git-worktree/scripts/worktree-manager.sh cleanup
Safety: Won't remove current worktree.
交互式移除闲置工作树。
bash
bash ~/.claude/skills/git-worktree/scripts/worktree-manager.sh cleanup
安全机制： 不会移除当前工作树。

Workflow Examples

工作流示例

Feature Development

功能开发

bash
undefined
bash
undefined

1. Create worktree from develop

1. 基于develop分支创建工作树

bash ~/.claude/skills/git-worktree/scripts/worktree-manager.sh create feature/auth-system
bash ~/.claude/skills/git-worktree/scripts/worktree-manager.sh create feature/auth-system

Script output:

脚本输出:

━━━ Launch Claude Code in this worktree ━━━

━━━ 在该工作树中启动Claude Code ━━━

cd /path/to/.github/worktrees/feature-auth-system && claude

cd /path/to/.github/worktrees/feature-auth-system && claude

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

2. CLAUDE STOPS HERE. Tells user to copy-paste the command above into a new terminal.

2. CLAUDE在此处停止操作。告知用户将上述命令复制粘贴到新终端中。

DO NOT continue with any work in this session.

请勿在当前会话中继续进行任何工作。

3. User pastes command → new Claude Code instance starts in the worktree

3. 用户粘贴命令 → 新的Claude Code实例在工作树中启动

User brainstorms, plans, and implements in that fresh session

用户在新会话中进行头脑风暴、规划和开发

4. When done, cleanup from main repo

4. 完成后，从主仓库清理工作树

cd "$(git rev-parse --show-toplevel)" bash ~/.claude/skills/git-worktree/scripts/worktree-manager.sh cleanup
undefined
cd "$(git rev-parse --show-toplevel)" bash ~/.claude/skills/git-worktree/scripts/worktree-manager.sh cleanup
undefined

PR Review in Isolation

隔离式PR评审

bash
undefined
bash
undefined

Create worktree from PR branch

基于PR分支创建工作树

bash ~/.claude/skills/git-worktree/scripts/worktree-manager.sh create pr-42-auth-fix origin/pr-branch
bash ~/.claude/skills/git-worktree/scripts/worktree-manager.sh create pr-42-auth-fix origin/pr-branch

CLAUDE STOPS HERE. Tells user to copy-paste the launch command into a new terminal.

CLAUDE在此处停止操作。告知用户将启动命令复制粘贴到新终端中。

Cleanup after review

评审完成后清理工作树

cd "$(git rev-parse --show-toplevel)" bash ~/.claude/skills/git-worktree/scripts/worktree-manager.sh cleanup
undefined
cd "$(git rev-parse --show-toplevel)" bash ~/.claude/skills/git-worktree/scripts/worktree-manager.sh cleanup
undefined

Directory Structure

目录结构

text
project-root/
├── .env                              # Source of truth
├── .github/
│   └── worktrees/                    # All worktrees live here
│       ├── feature-auth/
│       │   ├── .env -> ../../..      # Relative symlink to root .env
│       │   ├── src/
│       │   └── ...
│       └── feature-pipeline/
│           ├── .env -> ../../..      # Relative symlink to root .env
│           └── ...
└── .gitignore                        # Includes .github/worktrees
text
project-root/
├── .env                              # 唯一可信源
├── .github/
│   └── worktrees/                    # 所有工作树存储在此
│       ├── feature-auth/
│       │   ├── .env -> ../../..      # 指向根目录.env的相对符号链接
│       │   ├── src/
│       │   └── ...
│       └── feature-pipeline/
│           ├── .env -> ../../..      # 指向根目录.env的相对符号链接
│           └── ...
└── .gitignore                        # 已包含.github/worktrees

Troubleshooting

故障排除

"Worktree already exists"

"Worktree already exists"（工作树已存在）

Switch to it instead:
bash
bash ~/.claude/skills/git-worktree/scripts/worktree-manager.sh switch <name>
请切换到该工作树：
bash
bash ~/.claude/skills/git-worktree/scripts/worktree-manager.sh switch <name>

"Cannot remove worktree: it is current"

"Cannot remove worktree: it is current"（无法移除工作树：当前正处于该工作树）

Return to main repo first:
bash
cd "$(git rev-parse --show-toplevel)"
bash ~/.claude/skills/git-worktree/scripts/worktree-manager.sh cleanup
请先返回主仓库：
bash
cd "$(git rev-parse --show-toplevel)"
bash ~/.claude/skills/git-worktree/scripts/worktree-manager.sh cleanup

Symlink broken?

符号链接损坏？

Recreate manually from the worktree directory:
bash
cd .github/worktrees/<name>
rm .env
在工作树目录中手动重新创建：
bash
cd .github/worktrees/<name>
rm .env

Compute relative path to project root .env

计算指向项目根目录.env的相对路径

GIT_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel) ln -s "$(python3 -c "import os; print(os.path.relpath('$GIT_ROOT/.env', '$(pwd)'))")" .env ls -la .env # Verify
undefined
GIT_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel) ln -s "$(python3 -c "import os; print(os.path.relpath('$GIT_ROOT/.env', '$(pwd)'))")" .env ls -la .env # 验证
undefined

Why a New Terminal?

为什么需要新终端？

Claude Code's CWD and statusline are set at launch. If you 
cd
into a worktree from an existing session, the statusline stays wrong, and auto-compact causes Claude to revert to the main repo.
The script outputs a copy-paste command that:
  1. cd
    s to the worktree
  2. Launches a new 
    claude
    instance
This ensures correct statusline and stable context throughout the session.
Claude Code的当前工作目录（CWD）和状态行是在启动时设置的。如果在现有会话中
cd
到工作树，状态行将保持错误信息，且自动压缩功能会导致Claude切换回主仓库。
脚本输出的可复制命令会：
  1. cd
    到工作树目录
  2. 启动一个全新的
    claude
    实例
这样可以确保在整个会话过程中状态行正确且上下文稳定。