---
name: git-worktree
version: "1.1.0"
description: Git Worktree 管理命令。提供 init、list、remove 三个子命令来管理项目 worktree。
user-invocable: true
allowed-tools:
  - Bash
  - AskUserQuestion
---

# Git Worktree 管理命令 (v1.1.0)

管理项目中的 Git worktree，支持创建、列表查看和删除操作。

## 调用方式

```
/git-worktree init "任务描述"           # AI 自动生成分支名称
/git-worktree init "任务描述" --branch "分支名称"  # 指定分支名称
/git-worktree list                     # 列出所有 worktree
/git-worktree remove                   # 删除 worktree
```

## 命令详解

### init - 创建新的 Worktree

根据用户描述的任务，创建 worktree。**分支名称由 AI 根据任务描述自动生成**。

**调用方式：**
```
/git-worktree init "任务描述"
```

**参数说明：**
- `任务描述` - 任务的简短描述（必需）

**AI 生成分支名称的规则：**

AI 会根据任务描述生成分支名称，格式为 `<type>/<description>`，例如：
- "添加用户 Excel 导入导出功能" → `feature/user-excel-import-export`
- "修复登录页面样式问题" → `bugfix/login-page-style`
- "优化用户查询性能" → `refactor/user-query-performance`

分支类型前缀：
| 关键词 | 分支类型 |
|--------|----------|
| feat, 功能, 添加, 新增, 实现 | feature |
| fix, 修复, bug, 错误, 问题 | bugfix |
| refactor, 重构, 优化, 重写 | refactor |
| docs, 文档, 说明, readme | docs |
| test, 测试, 单元 | test |
| chore, 配置, 构建, 依赖 | chore |

名称要求：
- 必须是英文字母、数字和连字符
- 全部小写
- 简洁描述任务内容

**交互流程：**
1. AI 分析任务描述，生成分支名称
2. 执行脚本创建 worktree（传入分支名称）
3. 脚本输出 `[ASK_USER_OPEN_ITERM]` 标记和信息
4. AI 检测到标记后，使用 AskUserQuestion 询问用户是否打开 iTerm2
5. 用户同意后，执行以下命令打开 iTerm2：

```bash
cd /Users/lee0407/dev/projs/auth && python3 .claude/skills/git-worktree/scripts/open_iterm.py "<worktree_path>" "<branch_name>" "<description>"
```

**执行流程：**
1. AI 分析任务描述，生成英文分支名称（如 `feature/user-excel-import`）
2. 调用脚本创建 worktree，传入分支名称
3. 脚本基于 develop 分支创建新分支和 worktree
4. 输出 `[ASK_USER_OPEN_ITERM]` 标记，等待 AI 询问用户

**使用示例：**
```
/git-worktree init "添加用户 Excel 导入导出功能"
# AI 生成分支名称: feature/user-excel-import-export
# 创建 worktree 后询问是否打开 iTerm2
```

**指定分支名称（可选）：**
如果用户希望自定义分支名称，可以使用 `--branch` 参数：
```
/git-worktree init "任务描述" --branch "feature/custom-name"
```

## AI 响应规则

当执行 `/git-worktree init` 后，脚本会输出 `[ASK_USER_OPEN_ITERM]` 标记。AI 应：

1. **检测到 `[ASK_USER_OPEN_ITERM]` 标记**
2. **解析标记后的信息**（格式：`path|branch|description`）
3. **使用 AskUserQuestion 询问用户**：
```json
{
  "questions": [
    {
      "question": "是否要在 iTerm2 中打开新 tab 并启动 Claude？",
      "header": "iTerm2",
      "options": [
        {"label": "是，打开 iTerm2", "description": "在 iTerm2 新 tab 中启动 Claude"},
        {"label": "否，稍后手动打开", "description": "不打开，稍后自行执行"}
      ],
      "multiSelect": false
    }
  ]
}
```
4. **用户选择"是"后**，执行：
```bash
cd /Users/lee0407/dev/projs/auth && python3 .claude/skills/git-worktree/scripts/open_iterm.py "<worktree_path>" "<branch_name>" "<description>"
```

## 脚本说明

### worktree_manager.py
主脚本，处理 worktree 的创建、列表和删除操作。

### open_iterm.py
辅助脚本，用于在 iTerm2 中打开新 tab 并启动 Claude。

## 命令详解

### list - 列出所有 Worktree

显示当前仓库中所有 worktree 的列表。

**调用方式：**
```
/git-worktree list
```

**输出格式：**
```
Git Worktree 列表
============================================================
主 /Users/lee0407/dev/projs/auth                    [develop] ✓
└─ worktrees/feature-excel-import              [feature/excel-import] ✓
└─ worktrees/bugfix-login-issue                [bugfix/login-issue] ✗
============================================================
✓ = 干净工作区 | ✗ = 有未提交更改
```

**使用示例：**
```
/git-worktree list
```

### remove - 删除 Worktree

交互式删除指定的 worktree。

**调用方式：**
```
/git-worktree remove           # 交互式选择
/git-worktree remove 1         # 按索引删除
/git-worktree remove feature-xxx  # 按路径删除
```

**注意事项：**
- 不会删除主目录的 worktree
- 不会删除有未提交更改的 worktree（除非强制）

**使用示例：**
```
/git-worktree remove
# 显示可删除的 worktree 列表，供用户选择
```

## 工作原理

Git Worktree 允许在同一个仓库中同时在多个分支上工作：

```
auth/
├── .git/
├── worktrees/
│   ├── feature-excel-import/     # 功能开发 worktree
│   └── bugfix-login-issue/       # Bug 修复 worktree
├── auth-biz/
├── auth-server/
└── ...
```

## 最佳实践

1. **每个任务一个 worktree** - 保持工作区干净
2. **及时清理** - 任务完成后删除不需要的 worktree
3. **描述清晰** - 使用有意义的任务描述便于识别
4. **先更新 develop** - 创建前确保 develop 是最新的

## 注意事项

1. 所有 worktree 必须创建在 `worktrees/` 目录下
2. 创建前会自动检查 develop 分支是否为最新
3. 删除前会询问用户确认
4. 不会删除主目录的 worktree