isolate

Using Git Worktrees

Create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.

Core Principle

SYSTEMATIC DIRECTORY SELECTION + SAFETY VERIFICATION = RELIABLE ISOLATION.
Never create a worktree without verifying it's gitignored.

Steps

Step 1: Directory Selection

Follow this priority order:

1. Check existing directories:

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

   If found: Use that directory. .worktrees wins if both exist.

2. Check CLAUDE.md:

   grep -i "worktree.*director" CLAUDE.md 2>/dev/null
   

   If preference specified: Use it without asking.

3. Ask user (only if no directory exists and no preference):

   No worktree directory found. Where should I create worktrees?
   1. .worktrees/ (project-local, hidden)
   2. ~/.config/tn/worktrees/<project-name>/ (global location)
   

Step 2: Safety Verification

MUST verify directory is ignored before creating worktree:

git check-ignore -q .worktrees 2>/dev/null

If NOT ignored: Add to .gitignore and commit.

Step 3: Create Worktree

1. Detect project name: project=$(basename "$(git rev-parse --show-toplevel)")
2. Create worktree: git worktree add "$path" -b "$BRANCH_NAME"
3. Run project setup (auto-detect from package.json, Cargo.toml, etc.)
4. Verify clean baseline (run tests)
5. Record the baseline state (passing test count / suite output) so later tn:gate or tn:audit can compare against it
6. Report location

If no test command exists: degrade gracefully — record "no tests; baseline = clean checkout + setup completes" and note it in the report. Do not block isolation on a project that legitimately has no tests.

Red Flags

Thought	Reality
"Directory doesn't need gitignore"	Unignored worktrees pollute version control
"Skip baseline tests, just start"	Baseline test failure means environment issues — must resolve first
"Develop directly on the current branch"	Unisolated development pollutes the main branch
"Worktree is done once created"	Must verify the test baseline passes before starting work