Git Worktree

Git Worktree Setup

Create isolated git worktrees for feature development without switching branches.

Core principle: Smart directory selection + symlink optimization + background verification = fast, reliable isolation.

Requires: Git 2.5.0+ (July 2015)

Companion commands: [/git-worktree-status](./git-worktree-status.md) | [/git-worktree-remove](./git-worktree-remove.md) | [/git-worktree-clean](./git-worktree-clean.md)

Process

1. Validate Branch Name: Check naming convention and conflicts
2. Check Existing Directories: .worktrees/ or worktrees/
3. Verify .gitignore: Ensure worktree dir is ignored
4. Create Worktree: git worktree add
5. Symlink Dependencies: Reuse node_modules/ from main worktree
6. Detect Database Provider: Check for DB branching capability
7. Install Dependencies: Auto-detect package manager (if not symlinking)
8. Run Background Verification: Type check + tests in background
9. Report Location: Confirm ready with status

Flags

| Flag | Effect | |------|--------| | --fast | Skip dependency install and baseline tests | | --isolated | Fresh node_modules install (no symlink) | | --skip-install | Skip dependency install, keep baseline tests |

Branch Name Validation

# Auto-prefix based on naming convention
# "auth" → "feat/auth" (default prefix)
# "fix/login-bug" → kept as-is
# "refactor/db-layer" → kept as-is

# Accepted prefixes: feat/, fix/, refactor/, chore/, docs/, test/, perf/
# If no prefix → default to feat/

# Reject invalid characters
echo "$BRANCH_NAME" | grep -qE '^[a-zA-Z0-9/_-]+$' || exit 1

# Check branch doesn't already exist
git show-ref --verify --quiet "refs/heads/$BRANCH_NAME" && echo "Branch already exists" && exit 1

Directory Selection

Priority Order

# 1. Check existing directories
ls -d .worktrees 2>/dev/null     # Preferred (hidden)
ls -d worktrees 2>/dev/null      # Alternative

# 2. Check CLAUDE.md for preference
grep -i "worktree.*director" CLAUDE.md 2>/dev/null

# 3. Ask user if neither exists

If both exist: .worktrees/ wins.

Safety Verification

For project-local directories:

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

If NOT in .gitignore:

1. Add line to .gitignore
2. Commit the change
3. Proceed with worktree creation

Why critical: Prevents accidentally committing worktree contents.

Creation Steps

# 1. Detect project name
project=$(basename "$(git rev-parse --show-toplevel)")

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

# 3. Navigate
cd .worktrees/$BRANCH_NAME

Dependency Optimization (Node.js)

Default behavior: Symlink node_modules from main worktree to avoid duplicate installs (~30s saved).

# Symlink node_modules (default, unless --isolated)
if [ -d "../../node_modules" ] && [ ! "$ISOLATED" = true ]; then
  ln -s "$(cd ../.. && pwd)/node_modules" node_modules
  echo "Symlinked node_modules from main worktree"
fi

# With --isolated: fresh install
if [ "$ISOLATED" = true ]; then
  pnpm install   # or npm/yarn based on lockfile detection
fi

When to use --isolated:

• Schema changes requiring different package versions
• Testing dependency upgrades
• Debugging node_modules issues

Auto-Detect Setup (Multi-Stack)

# Node.js (if not symlinked)
if [ -f package.json ] && [ ! -L node_modules ]; then
  pnpm install   # Detect from lockfile: pnpm-lock.yaml / yarn.lock / package-lock.json
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

Background Verification

Instead of blocking on full test suite, run verification in background:

# Create log directory
mkdir -p .worktree-logs

# Background type check (Node.js)
if [ -f tsconfig.json ]; then
  npx tsc --noEmit > .worktree-logs/typecheck.log 2>&1 &
  echo "Type check running in background (check with /git-worktree-status)"
fi

# Background test run
if [ -f package.json ]; then
  npx vitest run --reporter=json > .worktree-logs/tests.log 2>&1 &
  echo "Tests running in background (check with /git-worktree-status)"
fi

With --fast: Skip all verification.

Final Report

Worktree ready at 
Branch: feat/auth (created from main)
Dependencies: symlinked from main worktree
Background checks: type check + tests running
Check status: /git-worktree-status

Ready to implement 

Database Branch Suggestion

After worktree creation, detect database provider and suggest isolation.

Quick Command Reference

| Provider | Suggested Command | |----------|-------------------| | Neon | neonctl branches create --name --parent main | | PlanetScale | pscale branch create | | Local Postgres | psql -c "CREATE SCHEMA ;" | | Other | Manual setup or shared DB |

Example output:

Worktree created at .worktrees/feat/auth

DB Isolation: neonctl branches create --name feat-auth --parent main
   Then update .env with new DATABASE_URL
   Full guide: ../workflows/database-branch-setup.md

.worktreeinclude Setup

Critical for environment variables:

# .worktreeinclude (at project root)
.env
.env.local
.env.development
**/.claude/settings.local.json

Why: Without this, .env files won't be copied to worktrees.

When to Create Database Branch

| Scenario | Create Branch? | |----------|---------------| | Schema migrations | Yes | | Data model refactoring | Yes | | Bug fix (no schema change) | No | | Performance experiments | Yes |

See: [Database Branch Setup Guide](../workflows/database-branch-setup.md) for complete workflows.

Quick Reference

| Situation | Action | |-----------|--------| | .worktrees/ exists | Use it (verify .gitignore) | | worktrees/ exists | Use it (verify .gitignore) | | Both exist | Use .worktrees/ | | Neither exists | Check CLAUDE.md, then ask user | | Not in .gitignore | Add + commit immediately | | No branch prefix | Auto-prefix with feat/ | | Node.js project | Symlink node_modules by default | | --fast flag | Skip install + tests | | --isolated flag | Fresh node_modules install | | Neon detected | Suggest neonctl branches create | | PlanetScale detected | Suggest pscale branch create | | No .worktreeinclude | Create with .env pattern |

Common Mistakes

Skipping .gitignore verification

• Worktree contents get tracked, pollute git status

Assuming directory location

• Follow priority: existing > CLAUDE.md > ask

Installing full node_modules in every worktree

• Wastes disk and time. Use symlink by default, --isolated only when needed

Not copying .env to worktree

• Symptom: Claude fails with "DATABASE_URL not found"
• Fix: Add .env to .worktreeinclude

Using shared database for schema changes

• Symptom: Migration conflicts, broken dev environment
• Fix: Create database branch before modifying schema

Usage

/git-worktree auth
/git-worktree fix/session-bug
/git-worktree feature/new-api --fast
/git-worktree refactor/db-layer --isolated

Branch name: $ARGUMENTS

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: FlorianBruniaux
• Source: FlorianBruniaux/claude-code-plugins
• License: MIT

Install and usage instructions live in the source repository linked above.