174 lines
4.4 KiB
Markdown
174 lines
4.4 KiB
Markdown
---
|
|
name: using-git-worktrees
|
|
description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with safety verification
|
|
---
|
|
|
|
# Using Git Worktrees
|
|
|
|
## Overview
|
|
|
|
Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.
|
|
|
|
**Core principle:** Use repo-root `.worktree/` + safety verification for reliable isolation.
|
|
|
|
**Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace."
|
|
|
|
## Directory Rule
|
|
|
|
Use repo-root `.worktree/` by default.
|
|
|
|
Do **not** suggest:
|
|
- `.worktrees/`
|
|
- `worktrees/`
|
|
- `~/.config/superpowers/worktrees/...`
|
|
|
|
Only deviate if the user explicitly asks for a different location.
|
|
|
|
## Safety Verification
|
|
|
|
**MUST verify `.worktree/` is ignored before creating a worktree:**
|
|
|
|
```bash
|
|
git check-ignore -q .worktree/ 2>/dev/null || git check-ignore -q .worktree 2>/dev/null
|
|
```
|
|
|
|
**If NOT ignored:**
|
|
|
|
Per Jesse's rule "Fix broken things immediately":
|
|
1. Add `.worktree/` to `.gitignore`
|
|
2. Commit the change
|
|
3. Proceed with worktree creation
|
|
|
|
**Why critical:** Prevents accidentally committing worktree contents to the repository.
|
|
|
|
## Creation Steps
|
|
|
|
### 1. Detect Project Name
|
|
|
|
```bash
|
|
project=$(basename "$(git rev-parse --show-toplevel)")
|
|
```
|
|
|
|
### 2. Create Worktree
|
|
|
|
```bash
|
|
path=".worktree/$BRANCH_NAME"
|
|
git worktree add "$path" -b "$BRANCH_NAME"
|
|
cd "$path"
|
|
```
|
|
|
|
### 3. Run Project Setup
|
|
|
|
Auto-detect and run appropriate setup:
|
|
|
|
```bash
|
|
# Node.js
|
|
if [ -f package.json ]; then npm install; fi
|
|
|
|
# Rust
|
|
if [ -f Cargo.toml ]; then cargo build; fi
|
|
|
|
# Python
|
|
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
|
|
if [ -f pyproject.toml ]; then poetry install; fi
|
|
|
|
# Go
|
|
if [ -f go.mod ]; then go mod download; fi
|
|
```
|
|
|
|
### 4. Verify Clean Baseline
|
|
|
|
Run tests to ensure worktree starts clean:
|
|
|
|
```bash
|
|
# Examples - use project-appropriate command
|
|
npm test
|
|
cargo test
|
|
pytest
|
|
go test ./...
|
|
```
|
|
|
|
**If tests fail:** Report failures, ask whether to proceed or investigate.
|
|
|
|
**If tests pass:** Report ready.
|
|
|
|
### 5. Report Location
|
|
|
|
```
|
|
Worktree ready at <full-path>
|
|
Tests passing (<N> tests, 0 failures)
|
|
Ready to implement <feature-name>
|
|
```
|
|
|
|
## Quick Reference
|
|
|
|
| Situation | Action |
|
|
|-----------|--------|
|
|
| Starting feature work | Use `.worktree/<branch-name>` |
|
|
| `.worktree/` not ignored | Add `.worktree/` to `.gitignore`, commit, continue |
|
|
| Tests fail during baseline | Report failures and ask |
|
|
| No package manager/build file | Skip dependency install |
|
|
| User explicitly wants another location | Follow the user's instruction |
|
|
|
|
## Common Mistakes
|
|
|
|
### Skipping ignore verification
|
|
|
|
- **Problem:** Worktree contents get tracked and pollute git status
|
|
- **Fix:** Always verify `.worktree/` is ignored first
|
|
|
|
### Using the wrong directory
|
|
|
|
- **Problem:** Inconsistent worktree layout across repositories
|
|
- **Fix:** Use repo-root `.worktree/` unless the user explicitly overrides it
|
|
|
|
### Proceeding with failing tests
|
|
|
|
- **Problem:** Can't distinguish new bugs from pre-existing issues
|
|
- **Fix:** Report failures and get explicit permission to proceed
|
|
|
|
### Hardcoding setup commands
|
|
|
|
- **Problem:** Breaks on projects using different tools
|
|
- **Fix:** Auto-detect from project files (`package.json`, `Cargo.toml`, etc.)
|
|
|
|
## Example Workflow
|
|
|
|
```
|
|
You: I'm using the using-git-worktrees skill to set up an isolated workspace.
|
|
|
|
[Verify .worktree/ is ignored]
|
|
[Create worktree: git worktree add .worktree/auth -b feature/auth]
|
|
[Run npm install]
|
|
[Run npm test - 47 passing]
|
|
|
|
Worktree ready at /Users/jesse/myproject/.worktree/auth
|
|
Tests passing (47 tests, 0 failures)
|
|
Ready to implement auth feature
|
|
```
|
|
|
|
## Red Flags
|
|
|
|
**Never:**
|
|
- Create a worktree without verifying `.worktree/` is ignored
|
|
- Skip baseline test verification
|
|
- Proceed with failing tests without asking
|
|
- Suggest `.worktrees/`, `worktrees/`, or `~/.config/superpowers/worktrees/...` by default
|
|
|
|
**Always:**
|
|
- Use repo-root `.worktree/` by default
|
|
- Verify `.worktree/` is ignored
|
|
- Auto-detect and run project setup
|
|
- Verify a clean test baseline
|
|
|
|
## Integration
|
|
|
|
**Called by:**
|
|
- **brainstorming** (Phase 4) - REQUIRED when design is approved and implementation follows
|
|
- **subagent-driven-development** - REQUIRED before executing any tasks
|
|
- **executing-plans** - REQUIRED before executing any tasks
|
|
- Any skill needing isolated workspace
|
|
|
|
**Pairs with:**
|
|
- **finishing-a-development-branch** - REQUIRED for cleanup after work complete
|