gwtm 0.1.0
Git Worktree Manager — manage worktrees across repositories
Requires Python: >=3.10

# gwtm — Git Worktree Manager

A CLI tool that simplifies working with [Git worktrees](https://git-scm.com/docs/git-worktree). Worktrees are stored centrally in `~/.worktrees/{repo}/{name}` instead of cluttering your project directories, making it easy to manage multiple branches across repositories.

## Why?

Git worktrees let you check out multiple branches simultaneously — each in its own directory, sharing a single `.git` repository. This is useful for:

- Running multiple Claude Code (or any AI coding agent) instances on different features in parallel
- Reviewing a PR while keeping your current work untouched
- Running tests on one branch while developing on another
- Hotfixing production without stashing or committing half-done work

**gwtm** removes the friction of managing worktree paths, branch naming, and cleanup by providing a simple CLI with shell integration and tab completion.

## Installation

Requires **Python 3.10+**.

```bash
# Install from PyPI
pip install gwtm

# Or with pipx (recommended for CLI tools)
pipx install gwtm
```

After installing, set up shell integration (see [Shell Integration](#shell-integration)).

## Quick Start

```bash
# Set up shell integration (add to your shell config)
eval "$(gwtm init-shell)"

# Navigate to any git repository
cd ~/projects/myapp

# Create a worktree for a new feature
gwtm new auth-refactor
# Creates ~/.worktrees/myapp/auth-refactor on branch wt/auth-refactor

# Jump into it
gwtm cd auth-refactor

# Work on something else in parallel
gwtm cd main
gwtm new fix-login --base develop

# Or attach a worktree to an existing branch
gwtm new hotfix --existing bugfix/issue-42

# Check status of all worktrees
gwtm status

# List worktrees
gwtm ls

# Sync with base branch
gwtm sync auth-refactor

# Done? Clean up
gwtm rm auth-refactor
```

## Commands

| Command | Description |
|---------|-------------|
| `gwtm new <name> [--base BRANCH] [--existing BRANCH]` | Create a new worktree (or attach to an existing branch) |
| `gwtm init [--force]` | Generate a `.gwtconfig.yaml` for the current repo |
| `gwtm ls [--all]` | List worktrees for the current repo (or all repos) |
| `gwtm cd <name>` | Change directory to a worktree (requires shell integration) |
| `gwtm path <name>` | Print the absolute path to a worktree |
| `gwtm rm <name> [--force] [--keep-branch]` | Remove a worktree and its branch |
| `gwtm sync [name] [--all]` | Rebase/merge worktree(s) with base branch |
| `gwtm status` | Show detailed status of all worktrees |
| `gwtm clean [--dry-run]` | Remove worktrees with already-merged branches |
| `gwtm clone <url> [--name NAME]` | Clone a repo with gwtm structure set up |
| `gwtm init-shell [--shell SHELL]` | Print shell integration code |

### Global Options

```
--version, -V    Show version
--verbose, -v    Show detailed output
--quiet, -q      Suppress non-essential output
--no-color       Disable colored output
```

### Fuzzy Matching

Commands that take a worktree name (`cd`, `rm`, `path`, `sync`) support fuzzy matching. If you type a partial name, gwtm will try to resolve it:

```bash
gwtm cd auth      # matches "auth-refactor" if it's the only match
gwtm cd main      # always resolves to the main worktree
```

If multiple worktrees match, gwtm shows suggestions.

## Shell Integration

Shell integration enables two features:
1. **`gwtm cd`** — actually changes your shell's working directory (without it, `cd` can't escape the subprocess)
2. **Tab completion** — autocompletes commands and worktree names

### Zsh

Add to `~/.zshrc`:

```zsh
eval "$(gwtm init-shell)"
```

### Bash

Add to `~/.bashrc`:

```bash
eval "$(gwtm init-shell)"
```

### Fish

Add to `~/.config/fish/config.fish`:

```fish
gwtm init-shell | source
```

## Configuration

gwtm uses a layered configuration system. Settings are merged in order: defaults < global config < per-repo config.

### Global Config

Created automatically on first run at `~/.config/gwtm/config.yaml`:

```yaml
worktrees_base: "~/.worktrees"      # Where worktrees are stored
branch_prefix: "wt/"                 # Prefix for new branches (e.g. wt/feature-x)
default_base_branch: "main"          # Base branch for new worktrees
sync_strategy: "rebase"              # "rebase" or "merge"
auto_fetch: true                     # Fetch before creating/syncing
clone_base: null                     # Base directory for gwtm clone
```

### Per-Repo Config

Create a `.gwtconfig.yaml` in any repository to override settings for that repo. The easiest way is with `gwtm init`:

```bash
gwtm init          # generates .gwtconfig.yaml with auto-detected defaults
gwtm init --force  # overwrite an existing config
```

This creates a commented template with all available options:

```yaml
default_base_branch: main

# branch_prefix: wt/
# sync_strategy: rebase
# auto_fetch: true
# carry_patterns:
#   - .env
#   - .ai
# carry_changes: false
```

The `gwtm clone` command also creates this file automatically with the detected default branch.

## How It Works

gwtm organizes worktrees in a central location:

```
~/.worktrees/
├── myapp/
│   ├── auth-refactor/      # branch: wt/auth-refactor
│   └── fix-login/          # branch: wt/fix-login
└── another-repo/
    └── new-feature/        # branch: wt/new-feature
```

When you run `gwtm new auth-refactor` inside `~/projects/myapp`:

1. Fetches latest from remote (if `auto_fetch` is enabled)
2. Creates branch `wt/auth-refactor` from the base branch
3. Creates a Git worktree at `~/.worktrees/myapp/auth-refactor`

You can also attach to an existing branch with `--existing`:

```bash
gwtm new hotfix --existing bugfix/issue-42
# Checks out the existing bugfix/issue-42 branch into ~/.worktrees/myapp/hotfix
```

The worktree shares the same `.git` history as your main repo — commits, stashes, and branches are all shared. You're just working in a separate checkout.

## Example: Parallel AI Coding Agents

A common workflow is running multiple AI coding agents on different features simultaneously:

```bash
# Terminal 1: Agent works on auth
gwtm new auth-system --base main
gwtm cd auth-system
# Start your AI agent here

# Terminal 2: Agent works on API
gwtm cd main
gwtm new api-endpoints --base main
gwtm cd api-endpoints
# Start another AI agent here

# Terminal 3: You monitor progress
gwtm status
```

Each agent gets its own isolated working directory with a separate branch, but they share the same Git history.

## Development

```bash
git clone https://github.com/vfosantos/worktree-manager.git
cd worktree-manager
pip install -e ".[dev]"
pytest
```

## License

MIT