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

Validate Branch Name: Check naming convention and conflicts
Check Existing Directories: .worktrees/ or worktrees/
Verify .gitignore: Ensure worktree dir is ignored
Create Worktree: git worktree add
Symlink Dependencies: Reuse node_modules/ from main worktree
Detect Database Provider: Check for DB branching capability
Install Dependencies: Auto-detect package manager (if not symlinking)
Run Background Verification: Type check + tests in background
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:

Add line to .gitignore
Commit the change
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

git-worktree