git-worktree

Git Worktree 管理器

此技能为整个开发工作流中的 Git worktree 管理提供统一接口。无论是隔离审查 PR，还是并行开发功能，此技能都能处理所有复杂操作。

此技能的功能

• 创建 worktree，基于主分支并使用清晰的分支名称
• 列出 worktree 及其当前状态
• 在 worktree 之间切换，以便并行工作
• 自动清理已完成的 worktree
• 在每个步骤中进行交互式确认
• 自动管理 .gitignore，确保包含 worktree 目录
• 自动将 .env 文件从主仓库复制到新的 worktree
• 自动信任 mise 和 direnv 配置中的开发工具，并提供安全的审查防护措施

重要：始终使用管理脚本

绝不要直接调用 git worktree add。 始终使用 worktree-manager.sh 脚本。

该脚本会处理原始 Git 命令无法完成的关键设置：

1. 从主仓库复制 .env、.env.local、.env.test 等文件
2. 根据分支安全规则信任开发工具配置：
   • mise：仅当配置与受信任基准分支相比未发生变化时才自动信任
   • direnv：仅对受信任的基础分支自动允许；审查 worktree 仍需手动操作
3. 确保 .worktrees 位于 .gitignore 中
4. 创建一致的目录结构

# ✅ CORRECT - Always use the script
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

何时使用此技能

在以下情形中使用此技能：

1. 代码审查（/ce:review）：如果当前不在目标分支上（PR 分支或指定的分支），则提供使用 worktree 隔离审查的选项
2. 功能开发（/ce:work）：始终询问用户要并行使用 worktree，还是直接在当前分支上开发
3. 并行开发：同时开发多个功能时
4. 清理：在 worktree 中完成工作后

使用方法

在 Claude Code 工作流中

此技能会由 /ce:review 和 /ce:work 命令自动调用：

# For review: offers worktree if not on PR branch
# For work: always asks - new branch or worktree?

手动使用

也可以直接在 bash 中调用此技能：

# Create a new worktree (copies .env files automatically)
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

# Switch to a worktree
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)
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

命令

create <branch-name> [from-branch]

使用给定的分支名称创建新的 worktree。

选项：

• branch-name（必填）：新分支和 worktree 的名称
• from-branch（可选）：用于创建新分支的基础分支（默认为 main）

示例：

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

执行步骤：

1. 检查 worktree 是否已存在
2. 从远程更新基础分支
3. 创建新的 worktree 和分支
4. 从主仓库复制所有 .env 文件（.env、.env.local、.env.test 等）
5. 根据分支安全规则信任开发工具配置：
   • 受信任的基础分支（main、develop、dev、trunk、staging、release/*）会与自身进行比较
   • 其他分支会与默认分支进行比较
   • 非受信任基础分支会跳过 direnv 自动允许，因为 .envrc 可以加载未经检查的文件
6. 显示 worktree 的路径，方便切换到该目录

list 或 ls

列出所有可用的 worktree、对应分支及其当前状态。

示例：

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

输出包含：

• worktree 名称
• 分支名称
• 当前所在的 worktree（以 ✓ 标记）
• 主仓库状态

switch <name> 或 go <name>

切换到现有 worktree 并进入其目录。

示例：

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

可选操作：

• 如果未提供名称，则列出可用的 worktree 并提示选择

cleanup 或 clean

交互式清理非活动 worktree，并请求确认。

示例：

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

执行步骤：

1. 列出所有非活动 worktree
2. 请求确认
3. 移除所选 worktree
4. 清理空目录

工作流示例

使用 Worktree 进行代码审查

# Claude Code recognizes you're not on the PR branch
# Offers: "Use worktree for isolated review? (y/n)"

# You respond: yes
# Script runs (copies .env files automatically):
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

# After review, return to main:
cd ../..
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh cleanup

并行开发功能

# For first feature (copies .env files):
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create feature-login

# Later, start second feature (also copies .env files):
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

# Switch between them as needed:
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

核心设计原则

KISS（保持简单）

• 一个管理脚本处理所有 worktree 操作
• 简单的命令搭配合理的默认值
• 交互式提示可防止意外操作
• 清晰的命名直接使用分支名称

注重默认配置

• 始终从 main 创建工作树（除非另有指定）
• 工作树存储在 .worktrees/ 目录中
• 分支名称将作为工作树名称
• 自动管理 .gitignore

安全第一

• 创建工作树前会确认
• 清理前会确认，以防误删
• 不会移除当前工作树
• 出现问题时提供清晰的错误消息

与工作流集成

/ce:review

不再总是创建工作树：

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

/ce:work

始终提供选择：

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

故障排除

“工作树已存在”

如果看到此提示，脚本会询问你是否要改为切换到该工作树。

“无法移除工作树：这是当前工作树”

先切换出该工作树（切换到主仓库），然后再清理：

cd $(git rev-parse --show-toplevel)
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh cleanup

在工作树中找不到方向？

查看你当前所在的位置：

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

工作树中缺少 .env 文件？

如果创建工作树时没有包含 .env 文件（例如，通过原始的 git worktree add 命令创建），请复制这些文件：

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

返回主仓库：

cd $(git rev-parse --show-toplevel)

技术细节

目录结构

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

.gitignore (updated to include .worktrees)

工作原理

• 使用 git worktree add 创建隔离环境
• 每个工作树都有自己的分支
• 一个工作树中的更改不会影响其他工作树
• 与主仓库共享 Git 历史记录
• 可以从任意工作树推送

性能

• 工作树轻量（仅使用文件系统链接）
• 无需复制仓库
• 共享 Git 对象以提高效率
• 比克隆或暂存并切换快得多