using-git-worktrees

1# Using Git Worktrees
2 
3## Overview
4 
5Ensure 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.
6 
7**Core principle:** Detect existing isolation first. Then use native tools. Then fall back to git. Never fight the harness.
8 
9**Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace."
10 
11## Step 0: Detect Existing Isolation
12 
13**Before creating anything, check if you are already in an isolated workspace.**
14 
15```bash
16GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
17GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
18BRANCH=$(git branch --show-current)
19```
20 
21**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:
22 
23```bash
24# If this returns a path, you're in a submodule, not a worktree — treat as normal repo
25git rev-parse --show-superproject-working-tree 2>/dev/null
26```
27 
28**If `GIT_DIR != GIT_COMMON` (and not a submodule):** You are already in a linked worktree. Skip to Step 2 (Project Setup). Do NOT create another worktree.
29 
30Report with branch state:
31- On a branch: "Already in isolated workspace at `<path>` on branch `<name>`."
32- Detached HEAD: "Already in isolated workspace at `<path>` (detached HEAD, externally managed). Branch creation needed at finish time."
33…