domains / software-engineering / git-worktree-isolation / using-git-worktrees

using-git-worktrees

Skill card

combined

The copies overlap heavily on directory selection, gitignore safety, project setup, and baseline tests, but they disagree on the core workflow. obra/superpowers adds a Step 0 that detects whether the agent is already in a worktree or a submodule, asks for consent, and prefers native harness worktree tools before falling back to git. The other three copies omit that detection/consent/native-tool layer and instead present a direct git-worktree procedure with a global ~/.config/superpowers/worktrees option. Crowning one copy would hide a real alternative: the obra version is a harness-aware isolation procedure, while the others are a simpler manual git-worktree setup.

Repositories

Other copies

Combined skill

---
name: using-git-worktrees
description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback
---

# Using Git Worktrees

## Overview

Ensure work happens in an isolated workspace. Prefer your platform's native worktree tools. Fall back to manual git worktrees only when no native tool is available.

**Core principle:** Detect existing isolation first. Then use native tools. Then fall back to git. Never fight the harness.

**Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace."

## Step 0: Detect Existing Isolation

Before creating anything, check if you are already in an isolated workspace.

```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)
BRANCH=$(git branch --show-current)
```

Submodule guard: `GIT_DIR != GIT_COMMON` is also true inside git submodules. Before concluding "already in a worktree," verify you are not in a submodule:

```bash
git rev-parse --show-superproject-working-tree 2>/dev/null
```

If `GIT_DIR != GIT_COMMON` and not in a submodule, you are already in a linked worktree. Skip to Step 2. Do not create another worktree. Report the path and branch state, including detached HEAD if applicable.

If `GIT_DIR == GIT_COMMON` or in a submodule, you are in a normal repo checkout. If the user has already indicated a worktree preference in instructions, honor it without asking. Otherwise ask for consent before creating a worktree. If the user declines, work in place and skip to Step 2.

## Step 1: Create Isolated Workspace

Try these mechanisms in order.

### 1a. Native Worktree Tools (preferred)

If you have a native worktree tool, such as `EnterWorktree`, `WorktreeCreate`, a `/worktree` command, or a `--worktree` flag, use it and skip to Step 2. Native tools handle directory placement, branch creation, and cleanup automatically. Using `git worktree add` when a native tool is available can create phantom state the harness cannot manage.

Only proceed to Step 1b if no native worktree tool is available.

### 1b. Git Worktree Fallback

Use this only if Step 1a does not apply.

#### Directory Selection

Follow this priority order. Explicit user preference always beats observed filesystem state.

1. Check instructions for a declared worktree directory preference. If specified, use it without asking.
2. Check for an existing project-local worktree directory:
   ```bash
   ls -d .worktrees 2>/dev/null
   ls -d worktrees 2>/dev/null
   ```
   If found, use it. If both exist, `.worktrees` wins.
3. If there is no other guidance available, default to `.worktrees/` at the project root.

If the user prefers a global location, use `~/.config/superpowers/worktrees/<project-name>/` and skip gitignore verification because it is outside the project.

#### Safety Verification (project-local directories only)

MUST verify the directory is ignored before creating a worktree:

```bash
git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
```

If not ignored, add the appropriate line to `.gitignore`, commit the change, then proceed. This prevents accidentally committing worktree contents to the repository.

#### Create the Worktree

```bash
path="$LOCATION/$BRANCH_NAME"
git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"
```

For a global location, use `~/.config/superpowers/worktrees/$project/$BRANCH_NAME`, where `project=$(basename "$(git rev-parse --show-toplevel)")`.

Sandbox fallback: If `git worktree add` fails with a permission error, tell the user the sandbox blocked worktree creation and work in the current directory instead. Then run setup and baseline tests in place.

## Step 2: Project Setup

Auto-detect and run appropriate setup:

```bash
if [ -f package.json ]; then npm install; fi
if [ -f Cargo.toml ]; then cargo build; fi
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
if [ -f pyproject.toml ]; then poetry install; fi
if [ -f go.mod ]; then go mod download; fi
```

## Step 3: Verify Clean Baseline

Run the project-appropriate test command, such as `npm test`, `cargo test`, `pytest`, or `go test ./...`.

If tests fail, report failures and ask whether to proceed or investigate. If tests pass, report ready.

Report:

```
Worktree ready at <full-path>
Tests passing (<N> tests, 0 failures)
Ready to implement <feature-name>
```

## Quick Reference

| Situation | Action |
|-----------|--------|
| Already in linked worktree | Skip creation |
| In a submodule | Treat as normal repo |
| Native worktree tool available | Use it |
| No native tool | Git worktree fallback |
| `.worktrees/` exists | Use it and verify ignored |
| `worktrees/` exists | Use it and verify ignored |
| Both exist | Use `.worktrees/` |
| Neither exists | Check instructions, then default `.worktrees/` or ask |
| Directory not ignored | Add to .gitignore and commit |
| Permission error on create | Sandbox fallback, work in place |
| Tests fail during baseline | Report failures and ask |
| No package.json/Cargo.toml | Skip dependency install |

## Common Mistakes

- Skipping ignore verification for project-local worktrees.
- Assuming directory location when ambiguous.
- Proceeding with failing baseline tests without asking.
- Hardcoding setup commands instead of auto-detecting project files.
- Using `git worktree add` when a native worktree tool is available.
- Creating a second worktree when already in an isolated workspace.

## Integration

Use this skill before executing implementation plans or any task that requires an isolated workspace. Pair it with branch-finishing or cleanup skills after work is complete.