using-git-worktrees

Using Git Worktrees

Feature work happens in an isolated workspace so the user's checkout stays untouched. Order of preference: detect isolation you already have, use a native worktree tool, fall back to manual git worktree last. Never fight the harness.

Step 0: Detect existing isolation

Before creating anything:

GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
git rev-parse --show-superproject-working-tree 2>/dev/null

• GIT_DIR != GIT_COMMON and the third command prints nothing: you are already in a linked worktree. Skip to Step 2. Do not nest another worktree.
• Third command prints a path: you are in a submodule, not a worktree. Treat as a normal checkout.
• GIT_DIR == GIT_COMMON: normal checkout. If the user has not already stated a worktree preference, ask: "Want me to set up an isolated worktree? It protects your current branch." Honor a declared preference without re-asking. If they decline, work in place and skip to Step 2.

Step 1: Create the workspace

1a. Native tool first. If the platform provides a worktree mechanism (a tool named like EnterWorktree, a /worktree command, a --worktree flag), use it and go to Step 2. Native tools handle placement, branch creation, and cleanup; running git worktree add alongside one creates phantom state the harness cannot see.

1b. Git fallback, only when no native tool exists.

Directory priority: explicit user preference, then an existing .worktrees/ (wins over worktrees/ if both exist), then default to .worktrees/ at the project root.

Verify the directory is ignored before creating anything in it:

git check-ignore -q .worktrees || { echo ".worktrees/" >> .gitignore && git add .gitignore && git commit -m "chore: ignore worktrees dir"; }

Then create and enter:

git worktree add ".worktrees/$BRANCH_NAME" -b "$BRANCH_NAME"
cd ".worktrees/$BRANCH_NAME"

If creation fails on a sandbox permission error, say so and work in the current directory instead; still run Steps 2 and 3 in place.

Step 2: Project setup

Detect and install: package.json gets npm install (or the repo's manager), Cargo.toml gets cargo build, requirements.txt gets pip install -r, pyproject.toml gets the project's tool, go.mod gets go mod download. No manifest, no install.

Step 3: Verify a clean baseline

Run the project's test command. All green: report "Worktree ready at <path>, N tests passing, ready to implement <feature>." Failures: report them and ask whether to proceed or investigate first. Without a clean baseline you cannot tell your bugs from pre-existing ones.

Good vs bad

Bad: Platform exposes EnterWorktree, agent runs git worktree add ../feature-x anyway. The harness does not know the directory exists; cleanup never happens; the next session finds a stale phantom worktree on a stale branch.

Good: Agent detects a normal checkout, sees EnterWorktree is available, uses it, runs npm install, runs the suite, reports "142 tests passing, ready to implement".

Verification

After setup, run git rev-parse --git-dir and git rev-parse --git-common-dir. Expect different paths (linked worktree) or an explicit user decision to work in place. Then run git status --short from the main checkout. Expect no worktree files appearing as untracked. If they appear, the worktree directory is not ignored: fix .gitignore before any commits happen.

Completion checklist

• [ ] Step 0 detection ran before any creation
• [ ] Native tool used when available; git fallback only otherwise
• [ ] User consent or declared preference honored
• [ ] Worktree directory verified ignored (fallback path)
• [ ] Dependencies installed per the repo's manifest
• [ ] Baseline tests run; failures reported before proceeding

Any box unchecked: not done. Fix or say so.

Footguns

• Nested worktrees. Creating a worktree while already inside one. Step 0 exists to prevent exactly this; run it every time, including after session resumes.
• Submodule false positive. Submodules also have GIT_DIR != GIT_COMMON. Without the superproject check you will misreport isolation and skip creating a workspace you actually need.
• Untracked worktree pollution. A project-local worktree directory that is not git-ignored dumps hundreds of files into git status and, worst case, into a commit. Check-ignore first, always.
• Building on a red baseline. If tests fail before you start, every later failure is ambiguous. Get an explicit go-ahead before working on top of failures.