# Using Git Worktrees

> Use when starting new feature work to create isolated git worktrees with smart directory selectio…

Use when starting new feature work to create isolated git worktrees with smart directory selection and safety verification. Keeps main branch clean while developing.

- Page: https://ss33.ai/skills/bbeierle12/using-git-worktrees-29096347297
- Publisher: bbeierle12
- Category: [Software Development](https://ss33.ai/skills/category/software-development-t44z8z) › [Source control & code review](https://ss33.ai/skills/category/software-development-t44z8z/source-control-and-code-review-jebezw)
- License: MIT
- Source: https://github.com/bbeierle12/skill-mcp-claude/blob/35af8f9b0ad543963eeae3ede4ead33ceffd9a6a/skills/using-git-worktrees/SKILL.md

## Skill

SKILL.md: https://ss33.ai/api/v1/ss33/download/bbeierle12/using-git-worktrees-29096347297

# Using Git Worktrees

## Core Principle

**Isolate feature work. Keep main clean.**

Git worktrees let you work on multiple branches simultaneously in separate directories.

## When to Use

- Starting a new feature
- Working on a bugfix while main development continues
- Need to context-switch without stashing
- Want clean separation between work streams

## Setup Process

### Step 1: Check for Existing Worktree Directory

```bash
# Check in priority order
ls -d .worktrees 2>/dev/null    # Preferred (hidden)
ls -d worktrees 2>/dev/null     # Alternative
```

If found: Use that directory.
If both exist: `.worktrees` wins.

### Step 2: Check CLAUDE.md for Preferences

```bash
grep -i "worktree.*director" CLAUDE.md 2>/dev/null
```

If preference specified: Use it without asking.

### Step 3: If No Directory Exists

Ask the user:
```
No worktree directory found. Where should I create worktrees?
1. .worktrees/ (project-local, hidden)
2. worktrees/ (project-local, visible)
3. ~/.config/superpowers/worktrees/<project-name>/ (global location)

Which would you prefer?
```

### Step 4: Verify .gitignore

```bash
# Check if directory pattern in .gitignore
grep -q "^\.worktrees/$" .gitignore || grep -q "^worktrees/$" .gitignore
```

If not present, add it:
```bash
echo ".worktrees/" >> .gitignore
# or
echo "worktrees/" >> .gitignore
```

## Creating a Worktree

### Standard Creation

```bash
# Determine branch name from feature
BRANCH_NAME="feature/descriptive-name"

# Create worktree with new branch
git worktree add ".worktrees/$BRANCH_NAME" -b "$BRANCH_NAME"

# Navigate to worktree
cd ".worktrees/$BRANCH_NAME"
```

### From Existing Branch

```bash
git worktree add ".worktrees/$BRANCH_NAME" "$BRANCH_NAME"
```

## Post-Creation Setup

### Install Dependencies

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

### Run Initial Tests

```bash
# Run test suite
npm test  # or appropriate command

# Report status
```

If tests fail: Report failures, ask whether to proceed or investigate.
If tests pass: Report ready.

## Worktree Management

### List Worktrees

```bash
git worktree list
```

### Remove Worktree

```bash
# After merging feature branch
git worktree remove ".worktrees/feature/branch-name"

# Force remove (if needed)
git worktree remove --force ".worktrees/feature/branch-name"
```

### Prune Stale Worktrees

```bash
git worktree prune
```

## Best Practices

### Naming Convention
- `feature/descriptive-name` for features
- `bugfix/issue-number-description` for bugs
- `hotfix/critical-issue` for urgent fixes

### Keep Worktrees Focused
- One feature per worktree
- Merge and remove when done
- Don't let worktrees accumulate

### Sync Regularly
```bash
# In worktree, get latest from main
git fetch origin
git rebase origin/main
```

## Completion Checklist

When feature is complete:
1. [ ] All tests pass
2. [ ] Code reviewed
3. [ ] Merged to main
4. [ ] Worktree removed
5. [ ] Branch deleted (if desired)

```bash
# Full cleanup
git checkout main
git pull
git worktree remove ".worktrees/feature/name"
git branch -d feature/name
```

## Announcement Template

At start of worktree creation:
```
"I'm using the using-git-worktrees skill to set up an isolated workspace for [feature name]."
```

On completion:
```
"Worktree ready at [full-path]
Tests passing ([N] tests, 0 failures)
Ready to implement [feature-name]"
```