using-git-worktrees

Use when starting new feature work to create isolated git worktrees with smart directory selection and safety verification. Keeps main branch clean while developing.

⭐2stars🔀0forks📁View on GitHub🕐Updated Dec 30, 2025

When & Why to Use This Skill

This Claude skill automates the management of Git worktrees, allowing developers to work on multiple features or bug fixes simultaneously in isolated directories. It streamlines the development workflow by handling directory selection, safety verification, dependency installation, and automated testing, ensuring the main branch remains clean while enabling seamless context switching.

Use Cases

  • Parallel Feature Development: Create isolated workspaces for new features to keep the main branch stable and deployable while working on long-term tasks.
  • Efficient Context Switching: Switch to urgent bugfixes or code reviews without the need for 'git stash' or losing uncommitted work in your primary environment.
  • Side-by-Side Comparison: Run and test different branches simultaneously in separate directories to compare performance, UI changes, or logic across versions.
  • Automated Workspace Onboarding: Automatically set up new worktrees with project-specific dependencies (Node.js, Rust, Python, Go) and run initial test suites to ensure immediate productivity.
nameusing-git-worktrees
descriptionUse when starting new feature work to create isolated git worktrees with smart directory selection and safety verification. Keeps main branch clean while developing.

Using Git Worktrees

Core Principle

Isolate feature work. Keep main clean.

Git worktrees let you work on multiple branches simultaneously in separate directories.

When to Use

  • Starting a new feature
  • Working on a bugfix while main development continues
  • Need to context-switch without stashing
  • Want clean separation between work streams

Setup Process

Step 1: Check for Existing Worktree Directory

# Check in priority order
ls -d .worktrees 2>/dev/null    # Preferred (hidden)
ls -d worktrees 2>/dev/null     # Alternative

If found: Use that directory. If both exist: .worktrees wins.

Step 2: Check CLAUDE.md for Preferences

grep -i "worktree.*director" CLAUDE.md 2>/dev/null

If preference specified: Use it without asking.

Step 3: If No Directory Exists

Ask the user:

No worktree directory found. Where should I create worktrees?
1. .worktrees/ (project-local, hidden)
2. worktrees/ (project-local, visible)
3. ~/.config/superpowers/worktrees/<project-name>/ (global location)

Which would you prefer?

Step 4: Verify .gitignore

# Check if directory pattern in .gitignore
grep -q "^\.worktrees/$" .gitignore || grep -q "^worktrees/$" .gitignore

If not present, add it:

echo ".worktrees/" >> .gitignore
# or
echo "worktrees/" >> .gitignore

Creating a Worktree

Standard Creation

# Determine branch name from feature
BRANCH_NAME="feature/descriptive-name"

# Create worktree with new branch
git worktree add ".worktrees/$BRANCH_NAME" -b "$BRANCH_NAME"

# Navigate to worktree
cd ".worktrees/$BRANCH_NAME"

From Existing Branch

git worktree add ".worktrees/$BRANCH_NAME" "$BRANCH_NAME"

Post-Creation Setup

Install Dependencies

# 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

Run Initial Tests

# Run test suite
npm test  # or appropriate command

# Report status

If tests fail: Report failures, ask whether to proceed or investigate. If tests pass: Report ready.

Worktree Management

List Worktrees

git worktree list

Remove Worktree

# After merging feature branch
git worktree remove ".worktrees/feature/branch-name"

# Force remove (if needed)
git worktree remove --force ".worktrees/feature/branch-name"

Prune Stale Worktrees

git worktree prune

Best Practices

Naming Convention

  • feature/descriptive-name for features
  • bugfix/issue-number-description for bugs
  • hotfix/critical-issue for urgent fixes

Keep Worktrees Focused

  • One feature per worktree
  • Merge and remove when done
  • Don't let worktrees accumulate

Sync Regularly

# In worktree, get latest from main
git fetch origin
git rebase origin/main

Completion Checklist

When feature is complete:

  1. All tests pass
  2. Code reviewed
  3. Merged to main
  4. Worktree removed
  5. Branch deleted (if desired)
# Full cleanup
git checkout main
git pull
git worktree remove ".worktrees/feature/name"
git branch -d feature/name

Announcement Template

At start of worktree creation:

"I'm using the using-git-worktrees skill to set up an isolated workspace for [feature name]."

On completion:

"Worktree ready at [full-path]
Tests passing ([N] tests, 0 failures)
Ready to implement [feature-name]"