git:create-worktree

Claude 命令：创建 Worktree

你的任务是为并行开发创建并设置 git worktree，同时自动检测和安装项目依赖项。

说明

重要：请严格按照以下步骤操作：

1. 检查当前状态：运行 git worktree list 显示现有 worktree，并运行 git status 确认仓库状态干净（没有可能造成问题的未提交更改）

2. 获取最新远程分支：运行 git fetch --all，确保本地已获取所有远程分支的信息

3. 解析用户输入：确定用户要创建什么：

   • <name>：创建带有自动检测类型前缀的 worktree
   • --list：仅显示现有 worktree，然后退出
   • 无输入：交互式询问用户名称

4. 根据名称自动检测分支类型：检查第一个词是否为已知分支类型。如果是，将其用作前缀，其余部分作为名称。如果不是，默认使用 feature/。

   已知类型： feature、feat、fix、bug、bugfix、hotfix、release、docs、test、refactor、chore、spike、experiment、review

   示例：

   • refactor auth system → refactor/auth-system
   • fix login bug → fix/login-bug
   • auth system → feature/auth-system（默认）
   • hotfix critical error → hotfix/critical-error

   名称规范化： 将空格转换为连字符，转换为小写，并移除除连字符和下划线以外的特殊字符

5. 创建每个 worktree 时： a. 构造分支名称：根据检测到的类型和规范化后的名称构建完整分支名称：

   • <prefix>/<normalized-name>（例如，feature/auth-system）

   b. 解析分支：确定分支是否在本地或远程存在，或者是否需要创建：

   • 如果分支在本地存在：git worktree add ../<project>-<name> <branch>
   • 如果分支在远程存在（origin/）：git worktree add --track -b <branch> ../<project>-<name> origin/<branch>
   • 如果分支不存在：询问用户要使用的基础分支（默认值：当前分支或 main/master），然后运行 git worktree add -b <branch> ../<project>-<name> <base>

   c. 路径约定：使用同级目录，命名格式为 ../<project-name>-<name>

   • 从当前目录提取项目名称
   • 使用规范化后的名称（而非完整分支名称及其前缀）
   • 示例：feature/auth-system → ../myproject-auth-system

   d. 创建 worktree：执行相应的 git worktree add 命令

   e. 检测依赖项：检查新 worktree 中的依赖文件，并确定是否需要进行设置：

   • package.json -> Node.js 项目（npm/yarn/pnpm/bun）
   • requirements.txt 或 pyproject.toml 或 setup.py -> Python 项目
   • Cargo.toml -> Rust 项目
   • go.mod -> Go 项目
   • Gemfile -> Ruby 项目
   • composer.json -> PHP 项目

   f. 检测包管理器（适用于 Node.js 项目）：

   • bun.lockb -> 使用 bun install
   • pnpm-lock.yaml -> 使用 pnpm install
   • yarn.lock -> 使用 yarn install
   • package-lock.json 或默认情况 -> 使用 npm install

   g. 自动设置：自动运行依赖项安装：

   • 切换到 worktree 目录并运行检测到的安装命令
   • 报告进度：“正在使用 [package manager] 安装依赖项……”
   • 如果安装失败，报告错误，但继续显示 worktree 创建摘要

6. 摘要：显示已创建 worktree 的摘要：

   • Worktree 路径
   • 分支名称（包含前缀的完整名称）
   • 设置状态（依赖项已安装或安装失败）
   • 快速导航命令：cd <worktree-path>

Worktree 路径约定

Worktree 将创建为同级目录，以便保持目录结构清晰：

~/projects/
  myproject/                # Main worktree (current directory)
  myproject-add-auth/       # Feature branch worktree (feature/add-auth)
  myproject-critical-bug/   # Hotfix worktree (hotfix/critical-bug)
  myproject-pr-456/         # PR review worktree (review/pr-456)

命名规则：

• 格式：<project-name>-<name>（使用名称部分，而非完整分支名称）
• 分支名称：<type-prefix>/<name>（例如，feature/add-auth）
• 目录名称仅使用 <name> 部分，以保持简洁

示例

功能 worktree（默认）：

> /git:create-worktree auth system
# Branch: feature/auth-system
# Creates: ../myproject-auth-system

修复 worktree：

> /git:create-worktree fix login error
# Branch: fix/login-error
# Creates: ../myproject-login-error

重构 worktree：

> /git:create-worktree refactor api layer
# Branch: refactor/api-layer
# Creates: ../myproject-api-layer

热修复 worktree：

> /git:create-worktree hotfix critical bug
# Branch: hotfix/critical-bug
# Creates: ../myproject-critical-bug

列出已有 worktree：

> /git:create-worktree --list
# Shows: git worktree list output

设置检测示例

使用 pnpm 的 Node.js 项目：

Detected Node.js project with pnpm-lock.yaml
Installing dependencies with pnpm...
✓ Dependencies installed successfully

Python 项目：

Detected Python project with requirements.txt
Installing dependencies with pip...
✓ Dependencies installed successfully

Rust 项目：

Detected Rust project with Cargo.toml
Building project with cargo...
✓ Project built successfully

常见工作流

快速创建功能分支

> /git:create-worktree new dashboard
# Branch: feature/new-dashboard
# Creates worktree, installs dependencies, ready to code

功能开发进行中时执行热修复

# In main worktree, working on feature
> /git:create-worktree hotfix critical bug
# Branch: hotfix/critical-bug
# Creates separate worktree from main/master
# Fix bug in hotfix worktree
# Return to feature work when done

无需暂存更改即可审查 PR

> /git:create-worktree review pr 123
# Branch: review/pr-123
# Creates worktree for reviewing PR
# Can run tests, inspect code
# Delete when review complete

实验或技术验证

> /git:create-worktree spike new architecture
# Branch: spike/new-architecture
# Creates isolated worktree for experimentation
# Discard or merge based on results

重要说明

• 分支锁定：每个分支一次只能在一个 worktree 中检出。如果某个分支已检出，该命令会告知你它所在的 worktree。

• 共享 .git：所有 worktree 共用同一个 Git 对象数据库。在任何 worktree 中提交的更改都能在其他 worktree 中看到。

• 工作目录需保持干净：该命令会检查是否存在未提交的更改，并在有更改时发出警告，因为在干净的状态下创建 worktree 最安全。

• 同级目录：worktree 始终创建为同级目录（使用 ../），以保持工作区井然有序。切勿在主仓库内创建 worktree。

• 自动安装依赖项：该命令会自动检测项目类型和包管理器，然后运行相应的安装命令，无需提示。

• 远程跟踪：对于远程分支，worktree 会通过正确的跟踪设置（--track 标志）创建，以确保拉取和推送正常工作。

清理

完成 worktree 的使用后，请使用正确的移除命令：

git worktree remove ../myproject-add-auth

如果 worktree 中有未提交的更改，则使用：

git worktree remove --force ../myproject-add-auth

切勿使用 rm -rf 删除 worktree——请始终使用 git worktree remove。

故障排除

“分支已检出”

• 运行 git worktree list 查看该分支在哪个位置检出
• 可以在该 worktree 中继续工作，或先将其移除

“无法创建 worktree——路径已存在”

• 目标目录已存在
• 可以将其移除，或选择其他 worktree 路径

“依赖项安装失败”

• 手动进入 worktree：cd ../myproject-<name>
• 直接运行安装命令，查看完整的错误输出
• 常见原因：缺少系统依赖项、网络问题、锁文件损坏

“检测到的类型不正确”

• 如果第一个词是已知类型，则会将其用作分支类型
• 若要强制指定类型，请以以下内容开头：fix、hotfix、docs、test、refactor、chore、spike、review
• 如果第一个词不是已知类型，默认类型为 feature/