git-worktrees

# Git Worktrees

Create isolated workspaces for parallel development without disrupting
current work.

## Purpose

Git worktrees allow multiple branches to be checked out simultaneously in
separate directories. This enables parallel work without stashing, context
switching, or polluting the main workspace. This skill provides structured
worktree creation with safety verification.

## When to Use

Use worktrees when:

- Starting feature work that shouldn't affect main workspace
- Working on multiple features in parallel
- Testing changes in isolation
- Running long processes while continuing other work
- Reviewing PRs without disrupting current work

Skip worktrees when:

- Quick single-file fixes
- Changes that don't need isolation
- The main workspace is already clean

## Directory Selection Priority

When creating worktrees, check these locations in order:

### 1. Check for Existing Worktree Directory

```text
Look for:
- .worktrees/ (hidden, preferred)
- worktrees/ (visible)

If both exist, prefer .worktrees/
```

### 2. Check Project Configuration

```text
Look in CLAUDE.md or project documentation for:
- Stated worktree location preference
- Project-specific conventions
```

### 3. Ask the User

If no preference found:

```text
"Where should worktrees be created?"
- .worktrees/ (project-local, hidden)
- worktrees/ (project-local, visible)
- External location (e.g., ~/worktrees/project-name/)
```

## Safety Verification

**Critical for project-local worktrees:**

Before creating a worktree in `.worktrees/` or `worktrees/`:

```text
MUST verify directory is ignored in git.

Check .gitignore for:
- .worktrees/
- worktrees/
```

**If NOT ignored:**

```text
1. Add to .gitignore
   echo ".worktrees/" >> .gitignore
   (or "worktrees/" depending on choice)

2. Commit the change
   git add .gitignore
   git commit -m "Add worktree directory to .gitignore"

3. Then proceed with worktree creation
```

**Why this matters:** Accidentally committing worktree contents create