using-git-worktrees

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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:

```bash
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:

   ```bash
   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:

   ```bash
   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.

From BB-84C/superpowers-lite, MIT.

More from BB-84C/superpowers-lite