UsingGitWorktrees

UsingGitWorktrees

Create isolated git workspaces for parallel development without switching branches.

Overview

Git worktrees create isolated working directories that share the same repository, allowing:

• Work on multiple branches simultaneously
• Isolated test environments
• Clean baseline for new features
• No stashing or switching required

Core principle: Systematic directory selection + safety verification = reliable isolation

Announce at start: "I'm using the UsingGitWorktrees skill to set up an isolated workspace."

Why Use Git Worktrees?

Benefits

✅ Multiple branches active: Work on feature branch while keeping main branch clean ✅ Isolated testing: Each worktree has its own working directory and build artifacts ✅ No switching: No need to stash changes or switch branches ✅ Clean baselines: Start new work with verified clean state ✅ Parallel CI: Run tests in multiple worktrees simultaneously

vs. Branch Switching

Directory Selection Process

Follow this priority order:

1. Check for Existing Worktree Directory

# Check in priority order
if [ -d .worktrees ]; then
    WORKTREE_DIR=".worktrees"
elif [ -d worktrees ]; then
    WORKTREE_DIR="worktrees"
fi

If found: Use that directory (.worktrees takes priority over worktrees)

2. Check CLAUDE.md for Preference

if [ -f CLAUDE.md ]; then
    grep -i "worktree.*director" CLAUDE.md
fi

If preference specified: Use it without asking user

3. Ask User

If no directory exists and no CLAUDE.md preference:

No worktree directory found. Where should I create worktrees?

1. .worktrees/ (project-local, hidden, recommended)
2. worktrees/ (project-local, visible)
3. ~/worktrees/<project-name>/ (global location)

Which would you prefer?

Recommendation: .worktrees/ keeps project directory clean while remaining local

Safety Verification

For Project-Local Directories (.worktrees or worktrees)

MUST verify directory is git-ignored before creating worktree:

# Check if directory is properly ignored
if ! git check-ignore -q .worktrees && ! git check-ignore -q worktrees; then
    echo "WARNING: Worktree directory is not ignored!"
    # Must fix before proceeding
fi

Why critical: Prevents accidentally committing worktree contents to repository

If NOT ignored - MUST fix immediately:

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

# Commit the change
git add .gitignore
git commit -m "chore: ignore git worktree directory"

For Global Directory (~/worktrees)

No .gitignore verification needed - outside project entirely

Worktree Creation Steps

Step 1: Detect Project Name

PROJECT=$(basename "$(git rev-parse --show-toplevel)")

Step 2: Determine Branch Name

# Sanitize branch name for filesystem
BRANCH_NAME="feature/user-authentication"
BRANCH_PATH=$(echo "$BRANCH_NAME" | tr '/' '-')  # feature-user-authentication

Step 3: Construct Worktree Path

case $WORKTREE_DIR in
  .worktrees|worktrees)
    WORKTREE_PATH="$WORKTREE_DIR/$BRANCH_PATH"
    ;;
  ~/worktrees/*)
    WORKTREE_PATH="$HOME/worktrees/$PROJECT/$BRANCH_PATH"
    ;;
esac

Step 4: Create Worktree with New Branch

# Create worktree and branch in one command
git worktree add "$WORKTREE_PATH" -b "$BRANCH_NAME"

# Navigate to new worktree
cd "$WORKTREE_PATH"

Alternative - checkout existing branch:

# If branch already exists
git worktree add "$WORKTREE_PATH" "$BRANCH_NAME"

Step 5: Auto-Detect and Run Project Setup

Detect project type and install dependencies:

# Node.js / JavaScript
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
    # OR
    pip install -e .
fi

# Go
if [ -f go.mod ]; then
    go mod download
fi

# NixOS (from home repository pattern)
if [ -f flake.nix ]; then
    nix develop --command bash -c "echo 'Development environment ready'"
fi

Step 6: Verify Clean Baseline

Run tests to ensure worktree starts in working state:

# Node.js
npm test

# Rust
cargo test

# Python
pytest

# Go
go test ./...

# NixOS
nix build
# OR
make build

If tests fail:

• Report failures clearly
• Ask whether to proceed or investigate
• Document known issues

If tests pass:

• Report success
• Show test count and duration
• Confirm ready for work

Step 7: Report Worktree Ready

Worktree created successfully

Location: /path/to/project/.worktrees/feature-user-authentication
Branch: feature/user-authentication
Tests: ✓ 47 passing (2.3s)

Ready to implement user authentication feature

Managing Worktrees

List All Worktrees

git worktree list

Output:

/path/to/project        abc1234 [main]
/path/to/.worktrees/feature-auth  def5678 [feature/user-authentication]
/path/to/.worktrees/bugfix-db     ghi9012 [bugfix/database-connection]

Remove Worktree

# Remove worktree (keeps branch)
git worktree remove .worktrees/feature-auth

# Force remove (even with uncommitted changes)
git worktree remove --force .worktrees/feature-auth

Prune Deleted Worktrees

# Clean up references to manually deleted worktrees
git worktree prune

Move to Different Worktree

# Just cd to it - no branch switching needed
cd .worktrees/feature-auth

Quick Reference

Common Patterns for Your Home Repository

Based on your NixOS home repository structure:

Building a NixOS Configuration

# Create worktree for system change
git worktree add .worktrees/sakhalin-upgrade -b feature/sakhalin-upgrade

cd .worktrees/sakhalin-upgrade

# Build without switching main worktree
make host/sakhalin/build

# If successful, deploy
make host/sakhalin/switch

Working on Multiple Hosts

# Multiple worktrees for different hosts
git worktree add .worktrees/rhea-config -b feature/rhea-jellyfin
git worktree add .worktrees/aion-config -b feature/aion-audio

# Work on both simultaneously
cd .worktrees/rhea-config
make host/rhea/build

cd ../aion-config
make host/aion/build

Testing Flake Changes

# Isolated worktree for flake updates
git worktree add .worktrees/flake-update -b chore/flake-update

cd .worktrees/flake-update

# Update and test
nix flake update
make dry-build

# If successful, merge to main

Common Mistakes

❌ Skipping Ignore Verification

Problem: Worktree contents get tracked, pollute git status in main worktree Fix: Always use git check-ignore before creating project-local worktree

❌ Assuming Directory Location

Problem: Creates inconsistency, violates project conventions Fix: Follow priority: existing → CLAUDE.md → ask user

❌ Proceeding with Failing Tests

Problem: Can't distinguish new bugs from pre-existing issues Fix: Report failures, get explicit permission to proceed

❌ Hardcoding Setup Commands

Problem: Breaks on projects using different tools Fix: Auto-detect from project files (package.json, Cargo.toml, etc.)

❌ Forgetting to Remove Old Worktrees

Problem: Disk space waste, confusion about active work Fix: Regularly run git worktree list and remove completed work

❌ Committing from Wrong Worktree

Problem: Changes go to wrong branch Fix: Always verify current branch before committing: git branch --show-current

Integration with Other Skills

Before UsingGitWorktrees:

• Use Brainstorming to clarify what feature needs isolation
• Ensure design is validated before creating worktree

After UsingGitWorktrees:

• Use WritingPlans to create implementation plan
• Use TestDrivenDevelopment for implementation in worktree
• Use Git skill for branching and commit workflows

Cleanup after work:

# Merge work back to main
git checkout main
git merge feature/user-authentication

# Remove worktree
git worktree remove .worktrees/feature-user-authentication

# Delete branch if done
git branch -d feature/user-authentication

Examples

Example 1: Feature development in isolation

User: "Set up isolated workspace for authentication feature"

→ Invoke UsingGitWorktrees skill
→ Announce: "I'm using the UsingGitWorktrees skill to set up an isolated workspace"
→ Check for existing worktree directory
→ Find: .worktrees/ exists
→ Verify: git check-ignore confirms .worktrees/ is ignored
→ Create: git worktree add .worktrees/feature-auth -b feature/user-authentication
→ Setup: npm install
→ Test: npm test → 47 passing
→ Report: "Worktree ready at /path/to/project/.worktrees/feature-auth"
→ Ready for implementation

Example 2: Parallel host configurations

User: "I need to work on both rhea and aion configurations simultaneously"

→ Invoke UsingGitWorktrees skill
→ Create worktree for rhea: .worktrees/rhea-jellyfin
→ Create worktree for aion: .worktrees/aion-audio
→ Both worktrees have clean baselines
→ Can build and test both in parallel
→ Switch between with cd, no branch switching needed

Example 3: First-time setup with no worktree directory

User: "Create worktree for database migration"

→ Invoke UsingGitWorktrees skill
→ Check: No .worktrees/ or worktrees/ directory exists
→ Check: No CLAUDE.md preference
→ Ask user: "Where should I create worktrees?"
→ User selects: .worktrees/ (hidden)
→ Verify: Not in .gitignore
→ Fix: Add .worktrees/ to .gitignore
→ Commit: "chore: ignore git worktree directory"
→ Create: git worktree add .worktrees/db-migration -b feature/db-migration
→ Setup and verify
→ Ready for work

Example 4: Cleanup after merge

User: "Clean up the authentication worktree now that it's merged"

→ Navigate to main worktree
→ Verify feature branch merged: git branch --merged
→ Remove worktree: git worktree remove .worktrees/feature-auth
→ Delete branch: git branch -d feature/user-authentication
→ Confirm: git worktree list shows worktree removed

Red Flags

Never:

• Create worktree without verifying it's ignored (project-local)
• Skip baseline test verification
• Proceed with failing tests without explicit permission
• Assume directory location when ambiguous
• Leave old worktrees around indefinitely
• Commit to wrong branch (verify with git branch --show-current)

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
• Report clear status when worktree is ready
• Clean up worktrees when work is merged