Git Worktrees

All worktrees go in ~/.worktrees/<repo-name>/<slug>/ — outside the project, no .gitignore needed.

Workflow

1. Create the worktree

MAIN_REPO="$(git rev-parse --show-toplevel)"
REPO_NAME="$(basename "$MAIN_REPO")"
WORKTREE="$HOME/.worktrees/$REPO_NAME/<slug>"

mkdir -p "$(dirname "$WORKTREE")"
git worktree add -b <branch-name> "$WORKTREE" <base-branch>
cd "$WORKTREE"

Derive <slug> from the branch name (e.g. fix/IH-694-missing-icon -> ih-694).

2. Run setup

Check for .cursor/worktrees.json first. If it exists, execute its hooks and skip steps 3–4.

See references/cursor-worktrees-json.md for full schema.

CONFIG="$WORKTREE/.cursor/worktrees.json"
[ ! -f "$CONFIG" ] && CONFIG="$MAIN_REPO/.cursor/worktrees.json"

if [ -f "$CONFIG" ]; then
  export ROOT_WORKTREE_PATH="$MAIN_REPO"
  # Read setup-worktree-unix (preferred) or setup-worktree (fallback)
  # Execute each command sequentially from $WORKTREE; stop on failure
fi

If the config handles deps and env files, skip to step 5.

3. Copy environment files

Only needed when no .cursor/worktrees.json handles this.

Worktrees don't inherit gitignored files. Copy (never symlink) .env* files from the main repo:

cd "$MAIN_REPO"
find . -name '.env*' -type f -not -name '*.sample' -not -path '*/node_modules/*' -not -path '*/.git/*' \
  | while read -r f; do
    if git check-ignore -q "$f" 2>/dev/null; then
      mkdir -p "$WORKTREE/$(dirname "$f")"
      cp "$f" "$WORKTREE/$f"
    fi
  done

Never use ln -s — glob-based tooling (bundlers, config loaders) silently ignores symlinks.

4. Install dependencies

Only needed when no .cursor/worktrees.json handles this.

Auto-detect from lockfile and run the matching install command:

Lockfile	Command
pnpm-lock.yaml	pnpm install
bun.lockb / bun.lock	bun install
yarn.lock	yarn install
package-lock.json	npm install
Cargo.toml	cargo build
requirements.txt	pip install -r requirements.txt
pyproject.toml	poetry install or pip install -e .
go.mod	go mod download

5. Verify and report

Run project-appropriate tests to confirm a clean baseline. If tests fail, report failures and ask before proceeding.

Worktree ready at ~/.worktrees/<repo>/<slug>
Branch: <branch-name>
Tests: <N> passing

Cleanup

git worktree remove ~/.worktrees/<repo-name>/<slug>        # normal
git worktree remove --force ~/.worktrees/<repo-name>/<slug> # uncommitted changes
git worktree prune                                          # stale refs

Pitfalls

Mistake	Why it breaks	Fix
Ignoring .cursor/worktrees.json	Duplicates or misses project-specific setup steps	Always check for config first
Symlinking .env files	Glob-based tooling silently skips symlinks	Always cp
Forgetting .env files	Missing secrets cause confusing runtime errors	Auto-discover with find + git check-ignore
Worktree inside the project	Risks committing worktree contents	Use ~/.worktrees/
Skipping baseline tests	Can't distinguish new bugs from pre-existing	Run tests, ask if they fail