Chapter 8: Git Worktrees & Branch Management
Modern feature development requires isolation. You need to work on a new feature without destabilizing your current working state, switch contexts without stashing half-finished work, and run parallel workstreams without constant branch switching. Git worktrees solve all of this.
What Are Git Worktrees?
A git worktree allows you to check out multiple branches of the same repository simultaneously — each in its own directory on disk.
Without worktrees, your single repository has one working directory. Switching branches changes all the files in that one directory. You must stash changes, commit work-in-progress, or risk losing state every time you context-switch.
With worktrees, you can have:
~/projects/myapp/on branchmain~/projects/myapp-feature-auth/on branchfeature/auth~/projects/myapp-hotfix-123/on branchhotfix/issue-123
All three are the same repository. Commits, tags, and history are shared. But each directory has its own working tree and staging area, completely isolated from the others.
This is the foundation of the Superpowers mandatory worktree isolation policy introduced in v4.2.0: every feature branch gets its own worktree, and the main branch is never directly modified.
Creating a New Development Branch
Follow these five steps when starting new work.
Step 1: Choose a Directory
Name the worktree directory to match the branch name. Keep it adjacent to your main working directory:
# Main repo lives at:
/Users/you/projects/myapp
# New worktree will live at:
/Users/you/projects/myapp--feature-user-auth
The double-dash convention (--) visually separates the project name from the branch name and makes it easy to identify worktrees with ls.
Step 2: Create the Branch and Worktree
# From inside the main repo directory:
git worktree add ../myapp--feature-user-auth -b feature/user-auth
# This creates:
# 1. A new branch named feature/user-auth
# 2. A new directory at ../myapp--feature-user-auth
# 3. That directory checked out to the new branch
To create a worktree from an existing branch:
git worktree add ../myapp--feature-user-auth feature/user-auth
Step 3: Safety Verification
Before doing any work, verify the worktree is correctly set up:
cd ../myapp--feature-user-auth
# Verify you are on the right branch
git branch --show-current
# Expected: feature/user-auth
# Verify the worktree is clean
git status
# Expected: nothing to commit, working tree clean
# Verify you branched from the right place
git log --oneline -5
# Should show recent main branch history as the base
Do not skip this step. Starting work in the wrong branch or on a dirty tree is a common source of confusing bugs.
Step 4: Project Setup
Some projects require additional setup after a fresh checkout. In your new worktree:
# Install dependencies (if node_modules are not shared)
npm install
# Copy environment files if needed
cp ../myapp/.env.local .env.local
# Generate any required files
npm run generate
Check your project's CLAUDE.md or README.md for the canonical setup steps.
Step 5: Baseline Tests
Before writing a single line of feature code, run the full test suite:
npm test
All tests must pass before you begin. If tests fail on a clean checkout, you have a pre-existing problem that must be resolved before your feature work begins. This baseline ensures that any test failures introduced during your work are caused by your changes, not inherited from the base branch.
Finishing a Development Branch
When your feature is complete and all tests pass, you have four options for what to do with the work.
The Four Options
| Option | When to Use | What Happens |
|---|---|---|
| Merge Locally | Small change, you have write access, no review needed | Branch merged into main, worktree removed |
| Create PR | Team project, review required, or CI gates must pass | PR opened on remote, worktree kept until PR merges |
| Keep As-Is | Work-in-progress, not ready to merge, may return later | Worktree and branch preserved, no action taken |
| Discard | Experiment that failed, work no longer needed | Branch and worktree permanently deleted |
Option A: Merge Locally
# Ensure tests pass
npm test
# Switch to main and merge
cd ../myapp
git checkout main
git pull origin main
git merge --no-ff feature/user-auth -m "feat: add user authentication"
# Remove the worktree
git worktree remove ../myapp--feature-user-auth
# Delete the branch
git branch -d feature/user-auth
Option B: Create a Pull Request
# Push the branch to remote
cd ../myapp--feature-user-auth
git push -u origin feature/user-auth
# Create the PR (using GitHub CLI)
gh pr create --title "feat: add user authentication" --body "..."
# The worktree stays alive until the PR is reviewed and merged
Option C: Keep As-Is
No action needed. The worktree and branch persist. Document the work-in-progress state in a comment or issue so it is not forgotten.
Option D: Discard
Warning: This is permanent and cannot be undone.
The discard option requires explicit confirmation. You must type the word "discard" when prompted. This prevents accidental deletion of work.
# Remove the worktree directory
git worktree remove --force ../myapp--feature-user-auth
# Delete the local branch
git branch -D feature/user-auth
# If pushed to remote, delete the remote branch too
git push origin --delete feature/user-auth
Only discard when you are certain the work has no value. If there is any doubt, use "Keep As-Is" and revisit later.
Managing Multiple Worktrees
To see all active worktrees for a repository:
git worktree list
Output example:
/Users/you/projects/myapp abc1234 [main]
/Users/you/projects/myapp--feature-auth def5678 [feature/user-auth]
/Users/you/projects/myapp--hotfix-99 ghi9012 [hotfix/issue-99]
To prune stale worktree references (after manually deleting directories):
git worktree prune
Main Branch Protection
The Superpowers protocol enforces one absolute rule about the main branch:
Never commit directly to main. Every change goes through a branch and worktree.
This is enforced by the v4.2.0 mandatory worktree isolation policy. Even small, "quick" fixes should use a worktree. The discipline of always working in isolation prevents an entire class of problems: accidental commits to main, conflated changes in a single branch, and loss of the ability to cleanly revert.
If you find yourself about to commit directly to main, stop. Create a worktree. It takes 30 seconds and prevents mistakes that can take hours to untangle.