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-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