---
name: using-git-worktrees
description: Use when starting implementation work that needs branch isolation — creates a .worktrees/ workspace before ship executes tasks
---

# Using Git Worktrees

Isolated workspace, same repo. `ship` calls this before every plan execution.

**RTK note:** `git` commands auto-proxied — run normally.

## Setup Steps

### 1. Ensure `.worktrees/` is gitignored

```bash
git check-ignore -q .worktrees 2>/dev/null || echo ".worktrees/" >> .gitignore && git add .gitignore && git commit -m "chore: gitignore .worktrees/"
```

### 2. Create worktree

```bash
git worktree add .worktrees/<branch-name> -b <branch-name>
```

Branch naming: `feat/<slug>`, `fix/<slug>`, `chore/<slug>` — derive from plan filename or task description.

### 3. Install dependencies

```bash
cd .worktrees/<branch-name>

# Auto-detect:
[ -f bun.lockb ] && bun install
[ -f package-lock.json ] && npm install
[ -f yarn.lock ] && yarn
[ -f Cargo.toml ] && cargo build
[ -f requirements.txt ] && pip install -r requirements.txt
```

### 4. Verify clean baseline

Run project test suite. Failing tests → report, stop.

### 5. Report ready

```
Worktree ready: .worktrees/<branch-name>/
Branch: <branch-name>
Tests: N passing
```

Pass `WORKTREE_PATH=.worktrees/<branch-name>` to all implementer subagents.

## Cleanup

Handled by `finishing-a-development-branch` — don't remove manually.

## Learned Rules

### gitignored-file-edit-and-verify-in-main-repo | fired:1 | 2026-06-11
Plan dispatched cursor-agent to worktree to edit `.claude/settings.json` (gitignored) → file absent from worktree; edit would no-op; verification step (readFileSync from worktree cwd) would pass against nothing — false-green. Advisor caught before dispatch.
Prevent: any plan wave that edits a gitignored file must (a) target main repo after merge, not worktree; (b) verify via the main repo absolute path. Check `git check-ignore -q <file>` before adding file to a worktree wave.

### gitignored-files-absent-from-worktree | fired:1 | 2026-06-06
Tried to read `apps/web/.dev.vars` from `.worktrees/feat/X/apps/web/.dev.vars` → file not found. Gitignored files are not copied when worktrees are created.
Prevent: always read gitignored files (`.dev.vars`, `.env`, `Docs/`) from the MAIN repo path, never from the worktree path. Pattern: `apps/web/.dev.vars` not `.worktrees/<branch>/apps/web/.dev.vars`.

## Red Flags

**Never:**
- Skip gitignore check for `.worktrees/`
- Proceed with failing baseline tests
- Use `/tmp` — worktrees stay inside project

## Integration

**Called by:** `ship` — first step before task dispatch
**Pairs with:** `finishing-a-development-branch` — cleanup after work complete