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`](../../commands/git-worktree-status.md) | [`/git-worktree-remove`](../../commands/git-worktree-remove.md) | [`/git-worktree-clean`](../../commands/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 ```bash # 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 ```bash # 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:** ```bash # 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 ```bash # 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). ```bash # 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) ```bash # 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:** ```bash # 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:** ```bash # .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