> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/obra/superpowers/llms.txt
> Use this file to discover all available pages before exploring further.

# Using Git Worktrees

> Set up isolated workspaces for feature development with automatic safety verification

Create isolated git worktrees for working on multiple branches simultaneously without switching contexts. This skill handles directory selection, safety verification, and project setup automatically.

## When to Use

Use this skill when:

* Starting feature work that needs isolation from your current workspace
* Before executing implementation plans
* Working on multiple features that need to coexist
* Wanting to preserve your current workspace state while experimenting

<Note>
  Always announce at start: "I'm using the using-git-worktrees skill to set up an isolated workspace."
</Note>

## Core Principle

**Systematic directory selection + safety verification = reliable isolation**

Git worktrees share the same repository while providing separate working directories. This allows concurrent work on different branches without the overhead of cloning.

## Directory Selection Process

The skill follows a strict priority order to determine where to create worktrees:

<Steps>
  <Step title="Check for existing directories">
    First checks if a worktree directory already exists:

    ```bash theme={null}
    ls -d .worktrees 2>/dev/null     # Preferred (hidden)
    ls -d worktrees 2>/dev/null      # Alternative
    ```

    If found, uses that directory. If both exist, `.worktrees` wins.
  </Step>

  <Step title="Check CLAUDE.md for preferences">
    If no directory exists, checks for a preference in CLAUDE.md:

    ```bash theme={null}
    grep -i "worktree.*director" CLAUDE.md 2>/dev/null
    ```

    If a preference is specified, uses it without asking.
  </Step>

  <Step title="Ask the user">
    If no directory exists and no CLAUDE.md preference, presents two options:

    1. `.worktrees/` - Project-local, hidden directory
    2. `~/.config/superpowers/worktrees/<project-name>/` - Global location
  </Step>
</Steps>

## Safety Verification

<Warning>
  For project-local directories (`.worktrees` or `worktrees`), the skill **must verify** the directory is ignored before creating a worktree.
</Warning>

### Project-Local Directories

Before creating a worktree:

```bash theme={null}
# Check if directory is ignored
git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
```

**If NOT ignored:**

Following the rule "Fix broken things immediately":

1. Add appropriate line to `.gitignore`
2. Commit the change
3. Proceed with worktree creation

**Why this is critical:** Prevents accidentally committing worktree contents to the repository.

### Global Directory

For `~/.config/superpowers/worktrees`, no `.gitignore` verification is needed - it's outside the project entirely.

## Creation Workflow

<Steps>
  <Step title="Detect project name">
    ```bash theme={null}
    project=$(basename "$(git rev-parse --show-toplevel)")
    ```
  </Step>

  <Step title="Create worktree">
    ```bash theme={null}
    # Determine full path based on location
    case $LOCATION in
      .worktrees|worktrees)
        path="$LOCATION/$BRANCH_NAME"
        ;;
      ~/.config/superpowers/worktrees/*)
        path="~/.config/superpowers/worktrees/$project/$BRANCH_NAME"
        ;;
    esac

    # Create worktree with new branch
    git worktree add "$path" -b "$BRANCH_NAME"
    cd "$path"
    ```
  </Step>

  <Step title="Run project setup">
    Auto-detects and runs appropriate setup commands:

    ```bash theme={null}
    # 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
    ```
  </Step>

  <Step title="Verify clean baseline">
    Runs tests to ensure the worktree starts clean:

    ```bash theme={null}
    npm test
    cargo test
    pytest
    go test ./...
    ```

    **If tests fail:** Reports failures and asks whether to proceed or investigate.

    **If tests pass:** Reports ready.
  </Step>

  <Step title="Report location">
    ```
    Worktree ready at <full-path>
    Tests passing (<N> tests, 0 failures)
    Ready to implement <feature-name>
    ```
  </Step>
</Steps>

## Quick Reference

| Situation                  | Action                     |
| -------------------------- | -------------------------- |
| `.worktrees/` exists       | Use it (verify ignored)    |
| `worktrees/` exists        | Use it (verify ignored)    |
| Both exist                 | Use `.worktrees/`          |
| Neither exists             | Check CLAUDE.md → Ask user |
| Directory not ignored      | Add to .gitignore + commit |
| Tests fail during baseline | Report failures + ask      |
| No package.json/Cargo.toml | Skip dependency install    |

## Common Pitfalls

<Accordion title="Skipping ignore verification">
  **Problem:** Worktree contents get tracked, pollute git status

  **Fix:** Always use `git check-ignore` before creating project-local worktree
</Accordion>

<Accordion title="Assuming directory location">
  **Problem:** Creates inconsistency, violates project conventions

  **Fix:** Follow priority: existing > CLAUDE.md > ask
</Accordion>

<Accordion title="Proceeding with failing tests">
  **Problem:** Can't distinguish new bugs from pre-existing issues

  **Fix:** Report failures, get explicit permission to proceed
</Accordion>

<Accordion title="Hardcoding setup commands">
  **Problem:** Breaks on projects using different tools

  **Fix:** Auto-detect from project files (package.json, Cargo.toml, etc.)
</Accordion>

## Example Workflow

```
You: I'm using the using-git-worktrees skill to set up an isolated workspace.

[Check .worktrees/ - exists]
[Verify ignored - git check-ignore confirms .worktrees/ is ignored]
[Create worktree: git worktree add .worktrees/auth -b feature/auth]
[Run npm install]
[Run npm test - 47 passing]

Worktree ready at /Users/jesse/myproject/.worktrees/auth
Tests passing (47 tests, 0 failures)
Ready to implement auth feature
```

## Red Flags

<Warning>
  **Never:**

  * Create worktree without verifying it's ignored (project-local)
  * Skip baseline test verification
  * Proceed with failing tests without asking
  * Assume directory location when ambiguous
  * Skip CLAUDE.md check
</Warning>

<Tip>
  **Always:**

  * Follow directory priority: existing > CLAUDE.md > ask
  * Verify directory is ignored for project-local
  * Auto-detect and run project setup
  * Verify clean test baseline
</Tip>

## Integration with Other Skills

<CardGroup cols={2}>
  <Card title="Called by" icon="arrow-right">
    * **brainstorming** (Phase 4) - Required when design is approved
    * **subagent-driven-development** - Required before executing tasks
    * **executing-plans** - Required before executing tasks
  </Card>

  <Card title="Pairs with" icon="link">
    * **finishing-a-development-branch** - Required for cleanup after work complete
  </Card>
</CardGroup>