gwtm 0.1.0

Git Worktree Manager — manage worktrees across repositories

gwtm — Git Worktree Manager

A CLI tool that simplifies working with Git worktrees. 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+.

# 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).

Quick Start

# 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:

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:

eval "$(gwtm init-shell)"

Bash

Add to ~/.bashrc:

eval "$(gwtm init-shell)"

Fish

Add to ~/.config/fish/config.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:

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:

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:

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:

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:

# 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

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

License

MIT