using-git-worktrees

name	using-git-worktrees
description	Use when isolation may materially improve feature work; preserve existing isolation and repository preferences.

Using Git Worktrees

Decide from context first

Before asking or acting, inspect the current context: direct instructions, project instructions, and durable memory for branch or worktree preferences. If a preference exists, follow it without reopening the decision. Do not embed a particular user's local repository policy in this shared skill.

If no preference exists, decide whether isolation materially changes the workflow: concurrent work, risky refactors, a protected current checkout, or harness-managed workspace lifecycle may make it valuable. Ask once only when isolation materially changes the workflow. A plan does not automatically require a worktree; a bounded change may safely proceed in the current checkout when isolation adds no material benefit.

Detect existing isolation

Before creating anything, inspect existing isolation:

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 indicates a linked worktree only when the checkout is not a submodule. Reuse an existing isolated checkout rather than nesting one. Record its path and branch or detached state before work begins.

Create isolation when chosen

Prefer native worktree tools when the harness provides them; they manage workspace lifecycle, branch state, and cleanup that raw Git cannot see. Use the harness's native worktree tools before falling back to git worktree add.

When native support is unavailable and the context calls for a manual worktree:

1. Honor an explicit directory preference. Otherwise reuse .worktrees/ or worktrees/ if present; if neither exists, default to .worktrees/ at the project root.

2. Set LOCATION to that final chosen directory, then verify that exact project-local directory is ignored before creation. An ignored sibling does not authorize the selected directory:

   git check-ignore -q "$LOCATION"
   

3. If it is not ignored, stop and surface the repository-state change required before creating a worktree. Do not silently pollute version control.

4. Create the branch and worktree only after the context preference or the focused isolation decision authorizes it:

   git worktree add "$LOCATION/$BRANCH_NAME" -b "$BRANCH_NAME"
   

If the harness blocks creation, report the limitation and follow the chosen in-place workflow rather than fighting the environment.

Setup and baseline

Run only the setup and baseline verification needed for the project and the requested work. Reuse a trustworthy existing baseline when its relevant state has not changed; otherwise run the focused project command that establishes the starting condition. Distinguish a pre-existing failure from a new regression before attributing it to the requested change.

Safety reminders

• Do not create a nested worktree inside existing isolation.
• Do not bypass native lifecycle tools with raw Git when native support exists.
• Do not create a project-local worktree before ignore safety is established.
• Do not turn a missing preference into repeated consent questions.
• Do not treat every plan as evidence that isolation is required.