---
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