cenmiao/openspec-sp-git-worktree

Git Worktree Skill

核心原则： Systematic directory selection + safety verification = reliable isolation

---

什么是 Git Worktree

Git worktree 允许你同时在多个分支上工作，每个 worktree 有独立的 working directory。

project-root/
├── .git/
├── worktrees/
│   ├── feature-auth/     (branch: feature-auth)
│   ├── feature-api/      (branch: feature-api)
│   └── bugfix-login/     (branch: bugfix-login)
└── ...

---

工作流程

┌─────────────────────────────────────────────────────────┐
│  Git Worktree Setup Process                             │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  1. 目录选择                                            │
│     ┌─────────────────────────────────────┐            │
│     │ 1. 检查 .worktrees/ 或 worktrees/    │            │
│     │ 2. 检查 CLAUDE.md 偏好               │            │
│     │ 3. 询问用户                         │            │
│     └─────────────────────────────────────┘            │
│           │                                            │
│           ▼                                            │
│  2. 安全验证（必须）                                   │
│     ┌─────────────────────────────────────┐            │
│     │ git check-ignore <directory>        │            │
│     │ 如果被忽略 → 继续                   │            │
│     │ 如果未被忽略 → 添加到.gitignore     │            │
│     └─────────────────────────────────────┘            │
│           │                                            │
│           ▼                                            │
│  3. 创建 Worktree                                      │
│     git worktree add "<path>" -b "<branch>"            │
│                                                         │
│  4. 项目 Setup                                          │
│     npm install / cargo build / etc.                   │
│                                                         │
│  5. 基线测试验证                                        │
│     运行测试确认环境正常                               │
│                                                         │
│  6. 报告位置                                            │
│     "Worktree ready at <full-path>"                    │
│                                                         │
└─────────────────────────────────────────────────────────┘

---

详细步骤

Step 1: 目录选择优先级

优先级顺序：

1. 检查已有目录

   • 检查 .worktrees/ 是否存在
   • 检查 worktrees/ 是否存在
   • 使用已存在的目录结构

2. 检查 CLAUDE.md 偏好

   • 读取项目的 CLAUDE.md 或 .claude.md
   • 查找 worktree 目录偏好设置

3. 询问用户

   • 如果以上都不存在，询问用户 preferred 位置

Step 2: 安全验证（必须）

验证工作目录是否被 git ignore：

git check-ignore <worktree-path>

如果被忽略： ✅ 继续

如果未被忽略：

# 添加到 .gitignore
echo "worktrees/" >> .gitignore
git add .gitignore
git commit -m "Ignore worktrees directory"

Jesse 规则： Fix broken things immediately. 如果 .gitignore 缺失，立即修复。

Step 3: 创建 Worktree

git worktree add "<full-path>" -b "<branch-name>"

分支命名：

• 功能开发：feature/<name>
• Bug 修复：bugfix/<name>
• 实验：experiment/<name>

Step 4: 项目 Setup

根据项目类型运行 setup：

# Node.js
npm install

# Python
pip install -r requirements.txt

# Rust
cargo build

# Go
go mod download

Step 5: 基线测试验证

运行项目测试确认环境正常：

# Node.js
npm test

# Python
pytest

# Rust
cargo test

必须确认： 基线测试通过，环境就绪。

Step 6: 报告位置

Worktree ready at <full-path>
Branch: <branch-name>
Tests: <pass/fail>

---

常用命令

# 列出所有 worktrees
git worktree list

# 创建新 worktree
git worktree add <path> -b <branch>

# 删除 worktree
git worktree remove <path>

# 清理已删除的 worktree 信息
git worktree prune

# 检查是否被 ignore
git check-ignore <path>

---

使用示例

用户：我要开始实现用户认证功能

助手：我使用 openspec-sp-git-worktree 技能来创建隔离工作空间。

**Step 1: 目录选择**
- 检查存在的工作树目录...
- 发现 `worktrees/` 目录

**Step 2: 安全验证**
- 验证 `worktrees/feature-auth` 是否被 ignore...
- ✅ 已忽略

**Step 3: 创建 Worktree**
- 执行：git worktree add "D:/project/worktrees/feature-auth" -b "feature/auth"

**Step 4: 项目 Setup**
- 执行：npm install

**Step 5: 基线测试**
- 执行：npm test
- ✅ 所有测试通过

**Step 6: 报告**
Worktree ready at D:/project/worktrees/feature-auth
Branch: feature/auth
Tests: 42 passing

---

常见错误

❌ 跳过 ignore 验证

后果： worktree 可能被意外提交

正确做法： 总是先验证 git check-ignore

❌ 假设目录位置

后果： 目录结构不一致，难以管理

正确做法： 按优先级选择，或询问用户

❌ 在测试失败时继续

后果： 后续开发基于错误环境

正确做法： 修复基线测试后再继续

---

与其他技能集成

• openspec-apply-change: 在 apply 前创建隔离环境
• openspec-sp-subagent-dev: 子代理开发前设置工作空间
• finishing-a-development-branch: 完成后清理 worktree