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

Ensure work happens in an isolated workspace when appropriate. Prefer platform-native worktree tools. Fall back to manual `git worktree` only when no native tool is available.

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

## Workflow

### 1. Detect Existing Isolation

Before creating anything, check whether you are already in a linked worktree:

```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)
git rev-parse --show-superproject-working-tree 2>/dev/null
```

If `GIT_DIR != GIT_COMMON` and `show-superproject-working-tree` is empty, you are already in a linked worktree. Do not create another one. Report the path and branch, then continue to project setup.

If `GIT_DIR == GIT_COMMON` or this is a submodule, treat it as a normal repo checkout.

### 2. Get Consent

If the user has not already declared a worktree preference, ask:

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

If the user declines, work in place and continue to project setup.

### 3. Create Isolated Workspace

Use mechanisms in this order:

1. Native worktree tool if the platform provides one, such as `EnterWorktree`, `WorktreeCreate`, `/worktree`, or a `--worktree` flag.
2. Manual `git worktree add` only if no native tool exists.

Manual directory priority:

1. Explicit user/instruction preference.
2. Existing project-local `.worktrees/`.
3. Existing project-local `worktrees/`.
4. Default to `.worktrees/` at the project root.

Before creating a project-local worktree, verify the chosen directory is ignored:

```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 that change, then proceed.

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

If `git worktree add` is blocked by sandbox permissions, tell the user and work in the current directory instead.

### 4. Project Setup

Auto-detect setup where appropriate:

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

### 5. Baseline Verification

Run project-appropriate tests before implementation when practical: `npm test`, `cargo test`, `pytest`, `go test ./...`, or equivalent.

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

## Never

- Create a worktree when already in a linked worktree.
- Use `git worktree add` when a native worktree tool exists.
- Skip submodule detection.
- Create a project-local worktree without ignore verification.
- Proceed from failing baseline tests without telling the user.