using-git-worktrees git:20261022.588be60A

Immutable. This exact content never changes and is served at /api/v1/blob/a91293abb27d6083.

---
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
license: MIT
---

# 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
# If this returns a path, you're in a submodule, not a worktree — treat as normal repo
git rev-parse --show-superproject-working-tree 2>/dev/null
```

**If `GIT_DIR != GIT_COMMON` (and not a submodule):** you are already in a linked worktree. Skip to
Step 2. Do NOT create another worktree. Report: *"Already in isolated workspace at `<path>` on branch
`<name>`."* (Detached HEAD: note that branch creation is needed at finish time.)

**If `GIT_DIR == GIT_COMMON` (or in a submodule):** you are in a normal repo checkout. Has the user
already indicated their worktree preference? If not, ask for consent:

> "Would you like me to set up an isolated worktree? It protects your current branch from changes."

Honor any existing declared preference without asking. If the user declines, work in place and skip
to Step 2.

## Step 1: Create Isolated Workspace

**Two mechanisms. Try them in this order.**

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

Do you already have a way to create a worktree? It might be a tool named like `EnterWorktree`,
`WorktreeCreate`, a `/worktree` command, or a `--worktree` flag. If so, use it and skip to Step 2.
Native tools handle directory placement, branch creation and cleanup automatically; using
`git worktree add` when you have one creates phantom state your harness cannot see or manage.

### 1b. Git Worktree Fallback

**Only if Step 1a does not apply.**

#### Directory Selection

Explicit user preference always beats observed filesystem state.

1. Check your instructions for a declared worktree directory preference.
2. Check for an existing project-local directory: `ls -d .worktrees` (preferred) or `ls -d worktrees`.
   If both exist, `.worktrees` wins.
3. Otherwise default to `.worktrees/` at the project root.

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

**MUST verify the directory is ignored before creating the worktree:**

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

**If NOT ignored:** add it to `.gitignore`, commit, then proceed. Prevents accidentally committing
worktree contents.

#### Create the Worktree

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

**Sandbox fallback:** if `git worktree add` fails with a permission error, tell the user the sandbox
blocked it and work in the current directory instead.

## Step 2: Project Setup

Run the project's install command from `AGENTS.md` § Comandos (`INSTALL_COMMAND`). If it is `N/A`,
skip this step. Do not guess stack-specific commands.

## Step 3: Verify Clean Baseline

Run the project's test command (`TEST_COMMAND`). If it is `N/A`, state that there is no automated
baseline.

**If tests fail:** report failures and ask whether to proceed or investigate. **If they 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 (Step 0) |
| In a submodule | Treat as normal repo (Step 0 guard) |
| Native worktree tool available | Use it (Step 1a) |
| No native tool | Git worktree fallback (Step 1b) |
| `.worktrees/` exists | Use it (verify ignored) |
| `worktrees/` exists | Use it (verify ignored) |
| Both exist | Use `.worktrees/` |
| Neither exists | Check instruction file, then default `.worktrees/` |
| Directory not ignored | Add to `.gitignore` + commit |
| Permission error on create | Sandbox fallback, work in place |
| Tests fail during baseline | Report failures + ask |
| `INSTALL_COMMAND` is `N/A` | Skip dependency install |

## Red Flags

**Never:**
- Create a worktree when Step 0 detects existing isolation
- Use `git worktree add` when you have a native worktree tool (e.g., `EnterWorktree`)
- Skip Step 1a by jumping straight to Step 1b's git commands
- Create a worktree without verifying it's ignored (project-local)
- Skip baseline test verification
- Proceed with failing tests without asking

**Always:**
- Run Step 0 detection first
- Prefer native tools over git fallback
- Follow directory priority: explicit instructions > existing project-local directory > default
- Verify the directory is ignored for project-local
- Use the project's `INSTALL_COMMAND` / `TEST_COMMAND`
- Verify a clean test baseline

## References

Read only when needed:

- [`references/common-mistakes.md`](references/common-mistakes.md) — the five recurring mistakes and
  their fixes.