# Git Worktree Patterns

## Overview

Git worktrees allow multiple working directories from single repository, enabling parallel work on different branches without stashing or switching.

## Basic Commands

### Create Worktree

```bash
# From main/develop branch
cd <repo>/develop
git pull

# Create new worktree
git worktree add <path> -b <branch-name>
```

### List Worktrees

```bash
git worktree list
```

### Remove Worktree

```bash
# From any location in repo
git worktree remove <path>

# Or manually
rm -rf <path>
git worktree prune
```

## Naming Patterns

### Directory Structure

```
repos/
├── document-api/
│   ├── develop/          # Main worktree
│   ├── fix-permissions/  # Feature worktree
│   └── add-tags/         # Another feature worktree
```

### Branch Naming

Format: `<username>/PI-XXXXX_<description>`

Examples:
- `nate/PI-70535_rename-folder-fix`
- `nate/PI-70361_upload-permissions`
- `nate/PI-69924_delete-access-level`

## Workflow Patterns

### Starting Work

```bash
# Navigate to develop
cd document-api/develop

# Update develop
git pull

# Create worktree for ticket
git worktree add ../pi-70535-rename-fix -b nate/PI-70535_rename-folder-fix

# Move to worktree
cd ../pi-70535-rename-fix
```

### During Work

```bash
# Normal git operations work in worktree
git status
git add .
git commit -m "PI-70535: Fix folder rename permissions"
git push -u origin nate/PI-70535_rename-folder-fix
```

### After PR Merge

```bash
# From anywhere in repo
git worktree remove ../pi-70535-rename-fix

# Clean up
git worktree prune
git branch -d nate/PI-70535_rename-folder-fix

# Update develop
cd develop
git pull
```

## Common Issues

### Worktree Already Exists

```bash
# Error: worktree already exists
# Solution: Remove old worktree first
git worktree remove <path>
git worktree prune
```

### Branch Already Exists

```bash
# Error: branch already exists
# Solution: Use existing branch or delete old one
git worktree add <path> <existing-branch>

# Or delete old branch
git branch -D <branch-name>
git worktree add <path> -b <branch-name>
```

### Locked Worktree

```bash
# If worktree shows as locked
git worktree unlock <path>
git worktree remove <path>
```

### Orphaned Worktrees

```bash
# Clean up references to deleted worktrees
git worktree prune
```

## Best Practices

### Keep Worktrees Short-Lived

- Create for specific ticket
- Remove after PR merged
- Don't accumulate many worktrees

### Use Descriptive Names

```bash
# ❌ Bad
git worktree add ../work -b fix

# ✅ Good
git worktree add ../rename-folder-fix -b nate/PI-70535_rename-folder-fix
```

### Always Branch from Latest

```bash
# Update base branch before creating worktree
cd develop
git pull
git worktree add ../feature -b username/PI-XXXXX_feature
```

### Clean Up Regularly

```bash
# List all worktrees
git worktree list

# Remove merged/abandoned worktrees
git worktree remove <path>
git worktree prune
```

## Advantages Over Branch Switching

### Parallel Work

Work on multiple tickets simultaneously without switching contexts:

```
Terminal 1: cd document-api/develop    # Review PRs
Terminal 2: cd document-api/feature-1  # Active development
Terminal 3: cd document-api/hotfix     # Emergency fix
```

### Preserve State

Each worktree maintains its own:
- Working directory state
- Staged changes
- Build artifacts
- IDE configuration

### Avoid Stashing

No need to stash changes when switching tasks:

```bash
# Traditional flow (with stashing)
git stash
git checkout other-branch
# ... do work ...
git checkout original-branch
git stash pop

# Worktree flow (no stashing)
cd ../other-worktree
# ... do work ...
cd ../original-worktree
# Everything still there
```

## Limitations

### Shared References

All worktrees share:
- Git objects
- Remote configuration
- Git hooks
- Submodules

### Disk Space

Each worktree requires full working directory (but shares `.git` objects).

### Cannot Checkout Same Branch

```bash
# Error: branch already checked out
# One branch can only be checked out in one worktree at a time
git worktree add ../dup -b existing-branch  # Fails if already checked out
```