git-worktree

name	git-worktree
description	Create isolated git worktrees for feature development without switching branches
argument-hint	<branch_name> [--from <base>]
effort	medium
when_to_use	Use when starting feature work that needs isolation from main workspace.
disable-model-invocation	true

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-remove | /git-worktree-clean

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 <full-path>
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 <feature-name>

Database Branch Suggestion

After worktree creation, detect database provider and suggest isolation.

Quick Command Reference

Provider	Suggested Command
Neon	neonctl branches create --name <branch> --parent main
PlanetScale	pscale branch create <db> <branch>
Local Postgres	psql -c "CREATE SCHEMA <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 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