using-git-worktrees

Using Git Worktrees

Overview

Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.

Location: Always use .worktrees/ (per CLAUDE.md)

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

Safety Verification

Verify .worktrees/ is ignored before creating worktree:

git check-ignore -q .worktrees 2>/dev/null

If NOT ignored: Add to .gitignore and commit before proceeding.

Why critical: Prevents accidentally committing worktree contents to repository.

Creation Steps

1. Create Worktree

git worktree add .worktrees/$BRANCH_NAME -b $BRANCH_NAME $BASE_BRANCH
cd .worktrees/$BRANCH_NAME

2. Run Project Setup

Laravel:

Fresh worktrees don't have vendor/ or node_modules/. Install dependencies first:

# 1. Create bootstrap/cache (required for composer)
mkdir -p bootstrap/cache

# 2. Install PHP dependencies
composer install --no-interaction

# 3. Run Laravel setup (migrations, seeds, caches)
php artisan migrate --seed

# 4. Build frontend assets (Vite manifest required for tests)
npm install && npm run build

Why this order matters:

• bootstrap/cache must exist before composer runs post-install scripts
• vendor/ must exist before artisan commands work
• Vite manifest must exist or tests using views will fail

Other projects: Auto-detect from project files:

if [ -f package.json ]; then npm install; fi
if [ -f Cargo.toml ]; then cargo build; fi
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
if [ -f pyproject.toml ]; then poetry install; fi
if [ -f go.mod ]; then go mod download; fi

3. Verify Baseline

Run tests to ensure worktree starts clean:

# Laravel
php artisan test

# Other
npm test / cargo test / pytest / go test ./...

If tests fail: Verify setup completed correctly (vendor/, node_modules/, Vite manifest all exist). Compare with main worktree to identify if failures are pre-existing.