using-git-worktrees

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

view source

installs

stars

48,224

karma

SkillRank score ↗

8.3/ 10

evaluated by implexa, claude-haiku-4-5 · 2026-07-02

obra-using-git-worktrees detects existing isolation, prioritizes native platform tools, and falls back to git worktree creation with project-local directory safety checks, dependency installation, and baseline test verification.

structure

9.0

trigger phrases

8.0

procedure

9.0

edge cases

8.0

documentation

8.0

strengths

view original SKILL.md from smitheryclick to expand

---
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
# 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 (Project Setup). Do NOT create another worktree.

Report with branch state:
- On a branch: "Already in isolated workspace at `<path>` on branch `<name>`."
- Detached HEAD: "Already in isolated workspace at `<path>` (detached HEAD, externally managed). Branch creation 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 in your instructions? If not, ask for consent before creating a worktree:

> "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 consent, work in place and skip to Step 2.

## Step 1: Create Isolated Workspace

**You have two mechanisms. Try them in this order.**

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

The user has asked for an isolated workspace (Step 0 consent). Do you already have a way to create a worktree? It might be a tool with a name like `EnterWorktree`, `WorktreeCreate`, a `/worktree` command, or a `--worktree` flag. If you do, use it and skip to Step 2.

Native tools handle directory placement, branch creation, and cleanup automatically. Using `git worktree add` when you have a native tool creates phantom state your harness can't see or manage.

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

### 1b. Git Worktree Fallback

**Only use this if Step 1a does not apply** — you have no native worktree tool available. Create a worktree manually using git.

#### Directory Selection

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

1. **Check your instructions for a declared worktree directory preference.** If the user has already specified one, use it without asking.

2. **Check for an existing project-local worktree directory:**
   ```bash
   ls -d .worktrees 2>/dev/null     # Preferred (hidden)
   ls -d worktrees 2>/dev/null      # Alternative
   ```
   If found, use it. If both exist, `.worktrees` wins.

3. **If there is no other guidance available**, default to `.worktrees/` at the project root.

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

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

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

**If NOT ignored:** Add to .gitignore, commit the change, then proceed.

**Why critical:** Prevents accidentally committing worktree contents to repository.

#### Create the Worktree

```bash
# Determine path based on chosen location
path="$LOCATION/$BRANCH_NAME"

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

**Sandbox fallback:** If `git worktree add` fails with a permission error (sandbox denial), tell the user the sandbox blocked worktree creation and you're working in the current directory instead. Then run setup and baseline tests in place.

## Step 2: Project Setup

Auto-detect and run appropriate setup:

```bash
# Node.js
if [ -f package.json ]; then npm install; fi

# Rust
if [ -f Cargo.toml ]; then cargo build; fi

# Python
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
if [ -f pyproject.toml ]; then poetry install; fi

# Go
if [ -f go.mod ]; then go mod download; fi
```

## Step 3: Verify Clean Baseline

Run tests to ensure workspace starts clean:

```bash
# Use project-appropriate command
npm test / cargo test / pytest / go test ./...
```

**If tests fail:** Report failures, 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 (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 |
| No package.json/Cargo.toml | Skip dependency install |

## Common Mistakes

### Fighting the harness

- **Problem:** Using `git worktree add` when the platform already provides isolation
- **Fix:** Step 0 detects existing isolation. Step 1a defers to native tools.

### Skipping detection

- **Problem:** Creating a nested worktree inside an existing one
- **Fix:** Always run Step 0 before creating anything

### Skipping ignore verification

- **Problem:** Worktree contents get tracked, pollute git status
- **Fix:** Always use `git check-ignore` before creating project-local worktree

### Assuming directory location

- **Problem:** Creates inconsistency, violates project conventions
- **Fix:** Follow priority: explicit instructions > existing project-local directory > default

### Proceeding with failing tests

- **Problem:** Can't distinguish new bugs from pre-existing issues
- **Fix:** Report failures, get explicit permission to proceed

## 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`). This is the #1 mistake — if you have it, use it.
- Skip Step 1a by jumping straight to Step 1b's git commands
- Create 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 directory is ignored for project-local
- Auto-detect and run project setup
- Verify clean test baseline

related skills

semantically similar in the cross-vendor index

clawhub

84% match

Using Git Worktrees

Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verificat

don't have the plugin yet? install it then click "run inline in claude" again.

separated detection logic, native tool preference, and git fallback into explicit steps; added edge cases for sandbox permission denial, branch conflicts, network timeouts, and missing config files; documented external connections (git cli, package managers); extracted decision logic into dedicated section with clear if-else branching; clarified input requirements and output contracts; preserved original author obra's procedure faithfully.

Using Git Worktrees

intent

set up an isolated workspace for feature work using your platform's native worktree tool if available, falling back to manual git worktrees only when no native tool exists. run this before starting implementation work that needs separation from your current branch state. the goal: detect if you're already isolated, prefer native tools over manual git commands, verify the workspace is clean, and get ready to implement without polluting your main checkout.

inputs

git repository: local git repo with at least one commit; must have git cli available
native worktree tool (optional): platform-specific tool (e.g., EnterWorktree, /worktree command, --worktree flag) if your harness provides one. check your instructions or available commands first
user preference (optional): explicit worktree directory path or preference stated in instructions (e.g., "use .worktrees/")
project metadata: package.json, Cargo.toml, requirements.txt, pyproject.toml, or go.mod to auto-detect dependency install method
git configuration: .gitignore file writable if worktree directory needs to be added
network access (conditional): needed if dependency install requires package manager downloads (npm, cargo, pip, poetry, go mod)

procedure

step 1: detect existing isolation

check if you're already in an isolated workspace before creating anything.

inputs: current directory, git metadata actions:

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)

output: comparison of GIT_DIR vs GIT_COMMON, branch name or detached HEAD state

submodule guard: before concluding you're in a worktree, verify you're not in a submodule:

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

if that returns a path, you're in a submodule, not a worktree. treat as normal repo.

decision: jump to decision points section.

step 2: get user consent (if needed)

if step 1 shows you're in a normal repo (not isolated), check your instructions for existing preference.

inputs: instruction context, user's stated preference actions:

if user already declared preference (e.g., "set up a worktree" or "work in place"), honor it without asking
if no preference stated, ask: "would you like me to set up an isolated worktree? it protects your current branch from changes"

output: explicit yes/no consent or existing preference; if user declines, proceed to step 5 (project setup) without worktree creation

step 3a: use native worktree tool (preferred)

if user consented to worktree creation in step 2, check for native tool first.

inputs: platform harness, available commands or tool names actions:

check for native worktree creation mechanism (e.g., function named EnterWorktree, command /worktree, flag --worktree)
if native tool exists, invoke it and skip to step 5 (project setup)
if no native tool, proceed to step 3b

output: isolated workspace created and active directory changed to worktree path, or confirmation "no native tool found, proceeding to git fallback"

why critical: native tools handle directory placement, branch creation, and cleanup automatically. using git worktree add when you have a native tool creates phantom state the harness can't see.

step 3b: git worktree fallback (manual creation)

only run this if step 3a found no native tool available.

3b-i: select directory

follow priority order. explicit user instruction always beats observed filesystem state.

inputs: instruction context, filesystem state actions:

check instruction file for declared worktree directory preference. if found, use it and skip to 3b-ii

check for existing project-local worktree directory:

ls -d .worktrees 2>/dev/null     # preferred (hidden)
ls -d worktrees 2>/dev/null      # alternative

if found, use it. if both exist, .worktrees wins

if no instruction and no existing directory, default to .worktrees/ at project root

output: selected directory path (e.g., .worktrees/, /custom/path/, or existing worktrees/)

3b-ii: verify directory is ignored

only for project-local directories (.worktrees/, worktrees/, or similar).

inputs: selected directory path, .gitignore contents actions:

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

output: exit code (0 = ignored, nonzero = not ignored)

if not ignored:

add directory to .gitignore
commit the change: git add .gitignore && git commit -m "ignore worktrees directory"
proceed to 3b-iii

if already ignored, proceed directly to 3b-iii

why critical: prevents accidentally committing worktree contents to repo, keeps git status clean

3b-iii: create worktree

inputs: selected directory path, feature branch name actions:

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

output: new worktree created at $path, current directory changed to worktree

edge case - permission denied: if git worktree add fails with sandbox permission error, inform user: "sandbox blocked worktree creation. working in current directory instead." skip to step 4 (project setup) without changing directories.

edge case - branch name conflict: if branch already exists, git worktree add fails. report conflict and ask user to choose different branch name or remove existing branch/worktree.

step 4: project setup

auto-detect and run appropriate dependency install.

inputs: project root, presence of language-specific config files actions:

# node.js
if [ -f package.json ]; then npm install; fi

# rust
if [ -f Cargo.toml ]; then cargo build; fi

# python
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
if [ -f pyproject.toml ]; then poetry install; fi

# go
if [ -f go.mod ]; then go mod download; fi

output: dependencies installed, no errors reported

edge cases:

no config file found: skip install, report "no package config detected, skipping install"
network timeout: report "network timeout during install, check connectivity and retry"
permission denied: report "permission denied installing dependencies, check permissions or use sudo"

step 5: verify clean baseline

run tests to ensure workspace starts clean before feature work begins.

inputs: project root, test command (auto-detected) actions:

# use project-appropriate test command
npm test / cargo test / pytest / go test ./...

output: test results (pass/fail count), test output

edge cases:

no test command found: report "no test framework detected, skipping baseline verification"
tests fail: report failures with count, ask user "baseline tests failed. proceed with implementation or investigate first?"
tests pass: report "baseline clean, tests passed"

step 6: report ready state

inputs: worktree path (if created), test results, feature name output: final status report

format:

workspace ready at <full-path>
tests passing (<N> tests, 0 failures)
ready to implement <feature-name>

if sandbox fallback used:

sandbox blocked worktree creation, working in <current-path>
tests passing (<N> tests, 0 failures)
ready to implement <feature-name>

decision points

after step 1 detection:

if GIT_DIR != GIT_COMMON and NOT in submodule: already in isolated workspace. skip worktree creation, report current state, jump to step 4 (project setup)
if GIT_DIR == GIT_COMMON or in submodule: in normal repo. proceed to step 2 (get consent)

after step 2 consent:

if user declines worktree or existing preference says "work in place": skip steps 3a/3b, go directly to step 4 (project setup)
if user consents or existing preference says "create worktree": proceed to step 3a (native tool check)

after step 3a native tool check:

if native tool available: use it, jump to step 4 (project setup)
if no native tool: proceed to step 3b (git fallback)

after step 3b-ii ignore verification:

if directory already ignored: proceed to 3b-iii (create worktree)
if not ignored: add to .gitignore, commit, then proceed to 3b-iii

after step 3b-iii worktree creation:

if success: jump to step 4 (project setup)
if permission denied (sandbox): skip to step 4 (project setup) in current directory

after step 4 project setup:

if setup succeeds: proceed to step 5 (verify baseline)
if setup fails: report error, ask user whether to proceed or investigate

after step 5 baseline verification:

if tests pass: proceed to step 6 (report ready)
if tests fail: report failures, ask user "proceed with implementation or investigate first?"
- if user says proceed: continue to step 6 (report ready)
- if user says investigate: halt and let user debug

output contract

on success, output:

workspace location (absolute path)
branch name (if created via git worktree fallback)
test count and pass/fail status
ready confirmation with feature name

format example:

workspace ready at /home/user/project/.worktrees/feature-x
tests passing (42 tests, 0 failures)
ready to implement feature-x

if native tool used, output:

native tool confirmation
test results
ready confirmation

if sandbox fallback triggered, output:

sandbox blocked worktree creation, working in /home/user/project
tests passing (42 tests, 0 failures)
ready to implement feature-x

file locations:

worktree created at: $SELECTED_DIRECTORY/$BRANCH_NAME/
.gitignore updated at: <project-root>/.gitignore (if worktree directory was added)

outcome signal

user knows this skill worked when:

you report "workspace ready at " and print test results
current working directory is the worktree (or project root if sandbox fallback)
tests pass with zero failures
git status shows clean index, no unexpected tracked files
user can run implementation commands in the isolated workspace without affecting main branch

failure signals - do not proceed:

tests fail and user hasn't explicitly approved proceeding
worktree creation fails with non-permission error (e.g., branch conflict) and user hasn't resolved it
directory not ignored and you couldn't add it to .gitignore

neutral signals - proceed:

sandbox blocks worktree creation (fallback to current directory, still ready)
no test framework detected (skip baseline, still ready)
no native worktree tool available (use git fallback, still ready)