Using Git Worktrees

Systematic procedures for creating isolated Git development workspaces that share a single repository, enabling parallel branch work without losing context.

Perfect for developers who need to work on multiple branches simultaneously or want to keep experimental work isolated from main workspace.

Core Benefit

Work on multiple branches without switching:

Keep main branch always ready
Experiment in isolation
Easy abandonment of failed experiments
Parallel testing of different approaches

Directory Selection Priority

Where to Create Worktrees

Priority Order:

.worktrees/ (project-local, gitignored)
worktrees/ (project-local, gitignored)
~/.config/superpowers/worktrees/ (global, organized by repo)

Always check .gitignore first to avoid accidental commits.

Safety Verification

Before Creating Worktree:

Check .gitignore:

BASH

grep -E "(^|/)\.?worktrees/" .gitignore

If not found, add it:
```
.worktrees/
worktrees/
```
Verify exclusion:
BASH
```
git check-ignore .worktrees/test
```

This prevents accidentally committing worktree directories.

Creation Process

Basic Worktree Creation

BASH

# Create new worktree
git worktree add .worktrees/feature-name

# With specific branch
git worktree add .worktrees/bugfix new-bugfix-branch

# From existing branch
git worktree add .worktrees/review-pr existing-branch

Project Setup Detection

Automatic setup for common project types:

Detected Setups

Node.js:

BASH

npm install
npm test  # Baseline verification

Rust:

BASH

cargo build
cargo test

Python:

BASH

pip install -r requirements.txt
# or
poetry install

Go:

BASH

go mod download
go test ./...

Baseline Test Validation

Before Starting Work:

Run full test suite
Verify all tests pass
Document any pre-existing failures

This proves your changes didn't break anything.

BASH

# In new worktree
cd .worktrees/feature-name

# Run tests
npm test  # or appropriate test command

# All green? Safe to proceed
# Failures? Document or fix first

Common Workflows

Feature Development

BASH

# Create isolated workspace
git worktree add .worktrees/new-feature

cd .worktrees/new-feature
npm install
npm test  # Baseline verification

# Develop feature...
git add .
git commit -m "Add feature"

# When done, merge or PR from here

Bug Investigation

BASH

# Investigate without disrupting main work
git worktree add .worktrees/bug-123 main

cd .worktrees/bug-123
# Reproduce bug
# Fix and test
# Commit fix

Code Review

BASH

# Review PR in isolation
git worktree add .worktrees/review-pr-456 pr-branch

cd .worktrees/review-pr-456
npm install
npm test
# Review changes, test locally

Parallel Experiments

BASH

# Try multiple approaches simultaneously
git worktree add .worktrees/approach-a
git worktree add .worktrees/approach-b

# Work on both, keep best one

Cleanup

Remove Worktree

BASH

# Delete worktree directory
rm -rf .worktrees/feature-name

# Remove worktree registration
git worktree prune

List Worktrees

BASH

git worktree list

Directory Organization

Project-Local (Recommended):

my-project/
├── .worktrees/        # Gitignored
│   ├── feature-a/
│   └── feature-b/
├── src/
└── .git/

Global Organization:

~/.config/superpowers/worktrees/
├── my-project/
│   ├── feature-a/
│   └── feature-b/
└── other-project/
    └── bugfix/

Best Practices

Do:

Always check .gitignore first
Run baseline tests in new worktrees
Use descriptive worktree names
Clean up unused worktrees regularly

Don't:

Commit worktree directories
Skip baseline test verification
Nest worktrees
Share worktrees between repos

Troubleshooting

Worktree won't delete:

BASH

git worktree remove --force worktree-name

Forgot to gitignore:

BASH

# Add to .gitignore
echo ".worktrees/" >> .gitignore

# Remove from git if already tracked
git rm -r --cached .worktrees/
git commit -m "Remove worktrees from tracking"

Tests fail in worktree but pass in main:

Check dependency installation
Verify branch is up to date
Look for environment differences

About This Skill

This skill was created by obra as part of the Superpowers Skills Collection.

Explore the collection for complementary git workflow and development methodology skills!

Systematic procedures for creating isolated Git development workspaces that enable parallel branch work without context switching.