gwt

# Git Worktree Manager (gwt)

## Problem

Nested worktree directories cause Next.js Turbopack to detect multiple lockfiles, IDE file watchers to get confused, and build tools to traverse into nested worktrees. Sibling worktrees clutter the code directory.

## Solution

Use a **centralized `worktrees/` folder** to keep all worktrees organized and your main code directory clean.

## Directory Structure

```
~/code/
├── my-project/                    # main repo
├── other-project/                 # another repo
└── worktrees/                     # all worktrees live here
    ├── my-project--feat-auth/
    ├── my-project--fix-bug/
    └── other-project--feat-x/
```

Naming: `{repo-name}--{branch-name}` (double dash separator, slashes become dashes)

## When to Use

- **Reviewing PRs** in isolation without switching branches
- **Parallel development** on multiple features
- **Testing changes** without affecting main branch state
- **Overnight/long-running** work that shouldn't block other work

## Commands

```bash
gwt new <branch> [from]   # Create worktree (copies .env files)
gwt ls                    # List worktrees for current repo
gwt go <branch>           # Output path (use: cd $(gwt go feat))
gwt switch <branch>       # Copy "cd <path> && claude" to clipboard
gwt rm <branch>           # Remove worktree + delete branch
gwt here                  # Show current worktree info
gwt path <branch>         # Alias for 'go'
```

### Flags

- `--json` - Machine-readable output
- `--no-env` - Skip .env file copying
- `--keep-branch` - Don't delete branch on rm

### Environment Variables

- `GWT_WORKTREE_DIR` - Override worktrees directory (default: `../worktrees`)

## Human Usage

### Starting a new session in a worktree

```bash
# Create worktree
gwt new feat/my-feature

# Copy switch command to clipboard and get instructions
gwt switch my-feature

# Paste the command to switch and start Claude session
# (command is already in clipboard)
```

### Quick switching

```bash
#