Tutorial Overview

Series index: Superpowers Tutorial Series

using-git-worktrees is Superpowers’ environment isolation skill. It helps you create an independent working directory when you start a new feature, so you can develop in parallel without interfering with other work.

What you will learn

• ✅ The core concept of Git worktrees
• ✅ Why you need isolated development environments
• ✅ The full worktree workflow
• ✅ How it fits with branch strategy
• ✅ Real-world use cases

Why Do We Need Git Worktrees?

Problems with traditional branch-based development

flowchart LR
    A[Working on the main branch] --> B[Urgent bug fix]
    B --> C[Stash current changes]
    C --> D[Switch branches]
    D --> E[Fix the bug]
    E --> F[Switch back]
    F --> G[Restore work]
    G --> H[Context lost]
    
    style C fill:#ffcccc
    style H fill:#ffcccc

The worktree solution

flowchart TD
    A[Main workspace] --> B[Start new feature]
    B --> C[Create a new worktree]
    C --> D[Independent directory]
    D --> E[Parallel development]
    E --> F[No interference]
    
    style C fill:#e1f5ff
    style D fill:#e1f5ff
    style F fill:#e8f5e9

Side-by-side comparison

Core Concepts of Git Worktrees

What is a worktree?

A Git worktree lets you create multiple independent working directories from the same repository. Each directory can:

• Check out a different branch
• Have its own staging area
• Run builds and tests independently
• Share Git objects to save disk space

Repository layout

repository.git/          # Main repository (bare repository)
├── objects/             # Shared object store
├── refs/                # Shared references
└── ...

worktree-main/           # Main workspace
├── .git/                # Points to repository.git
├── src/
└── ...

worktree-feature-a/      # Feature A workspace
├── .git/                # Points to repository.git
├── src/                 # Different branch
└── ...

worktree-feature-b/      # Feature B workspace
├── .git/                # Points to repository.git
├── src/                 # Another branch
└── ...

Worktree vs branch

Branch                  Worktree
------                  --------
Logical isolation       Physical isolation
Same directory          Different directories
Requires switching      Exists in parallel
Shared staging area     Independent staging area

Superpowers Worktree Skill Explained

When it triggers

using-git-worktrees automatically triggers in these scenarios:

1. Starting a new feature - after the design document is approved
2. Executing an implementation plan - right before implementation begins
3. Parallel development - when multiple features need to be built at the same time

Automatic workflow

sequenceDiagram
    participant U as User
    participant AI as AI assistant
    participant G as Git
    participant V as Verification

    U->>AI: Start implementing the tag feature
    AI->>AI: Trigger `using-git-worktrees`
    AI->>G: Check current state
    G-->>AI: Currently on main branch
    AI->>G: Create worktree: feature-tag-system
    G-->>AI: Worktree created successfully
    AI->>V: Run project tests
    V-->>AI: Tests passed
    AI->>U: Worktree ready, you can start developing
    
    Note over AI,U: Working directory: ../theme-stack-blog-feature-tag-system

Smart directory naming

Superpowers automatically generates meaningful directory names:

Repository: theme-stack-blog
New feature: tag system

Generated worktrees:
theme-stack-blog-feature-tag-system/
theme-stack-blog-fix-login-bug/
theme-stack-blog-refactor-api/

Complete Workflow

Step 1: Create the worktree

# Superpowers runs this automatically
# Syntax: git worktree add <path> -b <branch>

git worktree add ../theme-stack-blog-feature-tag -b feature/tag-system

Output:

Preparing worktree (new branch 'feature/tag-system')
HEAD is now at abc123 Add new documentation

Step 2: Verify the environment

# Enter the new worktree
cd ../theme-stack-blog-feature-tag

# Confirm the branch
git branch
# * feature/tag-system
#   main

# Confirm the directory structure
ls -la
# .git
# src/
# tests/
# ...

# Run baseline tests
npm test  # or pytest, etc.
# ✅ All tests passed

Step 3: Start developing

# Develop inside the new worktree
# Fully isolated from the main workspace

# Edit code
vim src/components/TagList.js

# Commit
git add .
git commit -m "feat: implement tag list component"

# The main workspace is unaffected and can keep moving

Step 4: Finish the feature

# All work is complete and tests have passed
# Ready to merge

# Option 1: merge into main
git checkout main
git merge feature/tag-system

# Option 2: create a Pull Request
git push origin feature/tag-system
# Create the PR on GitHub

# Option 3: keep the worktree for more testing
# Do not merge yet

Step 5: Clean up the worktree

# The feature has been merged; clean up the worktree

# Return to the main repository
cd ../theme-stack-blog

# Remove the worktree
git worktree remove ../theme-stack-blog-feature-tag

# Delete the branch if it has already been merged
git branch -d feature/tag-system

Common Worktree Commands

List worktrees

# List all worktrees
git worktree list

# Example output:
# /home/user/theme-stack-blog         abc1234 [main]
# /home/user/theme-stack-blog-feature def5678 [feature/tag]

Create a worktree

# Create a worktree for a new branch
git worktree add <path> -b <new-branch>

# Create a worktree for an existing branch
git worktree add <path> <existing-branch>

# Example
git worktree add ../myproj-feature -b feature/new-feature
git worktree add ../myproj-fix fix/existing-branch

Remove a worktree

# Remove the worktree (branch stays)
git worktree remove <path>

# Force remove (even with uncommitted changes)
git worktree remove <path> --force

# Example
git worktree remove ../myproj-feature

Clean up stale references

# Clean up deleted worktrees
git worktree prune

# Show detailed information
git worktree list --verbose

Real-World Use Cases

Scenario 1: Parallel development of multiple features

Main workspace: small bug fixes and maintenance
├── worktree-feature-a: Feature A development
├── worktree-feature-b: Feature B development
└── worktree-experiment: Technical experiment

Operations:

# Main workspace
cd ~/projects/myapp
git checkout main

# Feature A
cd ~/projects/myapp-feature-a
git checkout feature/a
# Develop Feature A

# Feature B
cd ~/projects/myapp-feature-b
git checkout feature/b
# Develop Feature B

# Need to switch? Just `cd`, no stash required!

Scenario 2: Fixing code review feedback

# PR needs changes
cd ~/projects/myapp-pr-fix

# Check out the PR branch
git checkout pr/123-fix

# Make the changes
# Main workspace is unaffected

# Push when done
git push origin pr/123-fix

Scenario 3: Multi-version maintenance

# Maintain several versions at the same time
git worktree add ../myapp-v1 v1.x
git worktree add ../myapp-v2 v2.x
git worktree add ../myapp-main main

# You can work on all of these in parallel:
# - Fix bugs in v1.x
# - Add features in v2.x
# - Develop new work in main

Scenario 4: Dependency and build isolation

# Different features may need different dependency versions
# Each worktree can have its own node_modules

worktree-feature-a/
└── node_modules/  # React 17

worktree-feature-b/
└── node_modules/  # React 18

Superpowers Worktree Configuration

Configuration file

git_worktrees:
  # Enable automatic worktree creation
  enabled: true
  
  # Directory naming pattern
  naming:
    pattern: "{repo}-{type}-{name}"
    # {repo} - repository name
    # {type} - feature/bugfix/hotfix
    # {name} - feature name (slugified)
  
  # Automatic verification
  verify:
    run_tests: true
    test_command: "npm test"  # or "pytest", "make test"
    timeout_seconds: 300
  
  # Cleanup policy
  cleanup:
    auto_remove_merged: true
    remind_stale_days: 7

Directory choice

git_worktrees:
  # Where to store workspaces
  location:
    # Option 1: sibling directory next to the repository (default)
    strategy: sibling
    # Generates: ../repo-name-feature
    
    # Option 2: centralized directory
    # strategy: centralized
    # base_path: ~/worktrees/
    # Generates: ~/worktrees/repo-name-feature/

Best Practices

1. Naming convention

# ✅ Good: clear and descriptive
git worktree add ../app-feature-auth -b feature/auth
git worktree add ../app-fix-login-bug -b fix/login-bug

# ❌ Bad: unclear names
git worktree add ../temp -b test1
git worktree add ../work -b abc

2. Clean up promptly

# Check and clean up regularly
git worktree list

# Remove merged worktrees
git worktree remove ../app-feature-auth

# Clean orphaned worktrees
git worktree prune

3. Build independently

# Each worktree builds independently
cd worktree-feature-a
npm install  # independent node_modules
npm run build

# This does not affect the other worktrees

4. Avoid shared state

# ❌ Do not share state across worktrees
# Each worktree should stay independent

# ✅ Correct approach
# - Independent node_modules
# - Independent .env files
# - Independent build outputs

Common Questions

Q1: What is the difference between Worktree and Stash?

Answer:

Q2: Do worktrees take up a lot of space?

Answer: Not much, because:

• Git objects are shared
• Only the working tree files are separate
• You can use symlinks to share node_modules

Q3: Can the branch in a worktree be pushed?

Answer: Yes, completely normally:

cd worktree-feature
git push origin feature/my-feature

Q4: How do you handle conflicts?

Answer: The same way you do in a normal branch:

# Inside the worktree
git pull origin main
# If there are conflicts, resolve them normally
git merge --abort  # if you need to give up

How using-git-worktrees Works with Other Superpowers Skills

With brainstorming

brainstorming complete
    ↓
using-git-worktrees creates an isolated environment
    ↓
implementation begins

With writing-plans

Plan complete
    ↓
using-git-worktrees creates the environment
    ↓
`subagent-driven-development` executes

With TDD

Worktree created and verified
    ↓
test-driven-development begins
    ↓
Write tests in the isolated environment

Summary

using-git-worktrees provides a physically isolated development environment:

1. Parallel development - multiple features can move forward at the same time
2. Context protection - no need to stash and switch back and forth
3. Safe isolation - experiments do not affect the main workspace
4. Independent dependencies - different versions can coexist

Key takeaways

• ✅ Each feature gets its own worktree
• ✅ Clean up finished worktrees promptly
• ✅ Build and test independently
• ✅ Use clear naming conventions

Command reference

# Create
git worktree add <path> -b <branch>

# List
git worktree list

# Remove
git worktree remove <path>

# Clean up
git worktree prune

Series navigation:

• ← Previous: Tutorial 5: systematic-debugging - Systematic Debugging Method
• → Next: Tutorial 7: Complete Guide to Code Review Skills
• Back: Series Index

References

• Git Worktree official documentation
• Git Worktree best practices
• Parallel development with worktrees