gtr - Git Worktree Runner

A portable, cross-platform CLI for managing git worktrees with ease

Table of Contents

• What are git worktrees?
• Quick Start
• Why gtr?
• Features
• Requirements
• Commands
• Configuration
• Shell Completions
• Platform Support
• Contributing
• License

---

What are git worktrees?

ELI5: Normally, you can only work on one git branch at a time in a folder. Want to fix a bug while working on a feature? You have to stash changes, switch branches, then switch back. Git worktrees let you have multiple branches checked out at once in different folders - like having multiple copies of your project, each on a different branch.

The Problem: Everyone's using git worktrees wrong (or not at all):

• Constantly stashing/switching branches disrupts flow
• Running tests on main while working on features requires manual copying
• Reviewing PRs means stopping current work
• Parallel AI agents on different branches? Nearly impossible without worktrees

Why people sleep on worktrees: The DX is terrible. git worktree add ../my-project-feature feature is verbose, manual, and error-prone.

Enter gtr: Simple commands, AI tool integration, automatic setup, and built for modern parallel development workflows.

Quick Start

Homebrew (macOS):

brew tap coderabbitai/tap
brew install git-gtr

Script installer (macOS / Linux):

git clone https://github.com/coderabbitai/git-worktree-runner.git
cd git-worktree-runner
./install.sh

Other installation options

macOS (Intel) / Linux:

sudo mkdir -p /usr/local/bin
sudo ln -s "$(pwd)/bin/git-gtr" /usr/local/bin/git-gtr

User-local (no sudo required):

mkdir -p ~/.local/bin
ln -s "$(pwd)/bin/git-gtr" ~/.local/bin/git-gtr
# Add to ~/.zshrc or ~/.bashrc if ~/.local/bin is not in PATH:
# export PATH="$HOME/.local/bin:$PATH"

Usage:

# Navigate to your git repo
cd ~/GitHub/my-project

# One-time setup (per repository)
git gtr config set gtr.editor.default cursor
git gtr config set gtr.ai.default claude

# Daily workflow
git gtr new my-feature          # Create worktree folder: my-feature
git gtr new my-feature --editor # Create and open in editor
git gtr new my-feature --ai     # Create and start AI tool
git gtr new my-feature -e -a    # Create, open editor, then start AI
git gtr editor my-feature       # Open in cursor
git gtr ai my-feature           # Start claude

# Run commands in worktree
git gtr run my-feature npm test # Run tests

# Navigate to worktree
gtr new my-feature --cd         # Create and cd (requires shell integration)
gtr cd                          # Interactive picker (requires fzf + shell integration)
gtr cd my-feature               # Requires shell integration (see below)
cd "$(git gtr go my-feature)"   # Alternative without shell integration

# List all worktrees
git gtr list

# Remove when done
git gtr rm my-feature

# Or remove all worktrees with merged PRs/MRs (requires gh or glab CLI)
git gtr clean --merged

Why gtr?

While git worktree is powerful, it's verbose and manual. git gtr adds quality-of-life features for modern development:

Task	With git worktree	With git gtr
Create worktree	git worktree add ../repo-feature feature	git gtr new feature
Create + open	git worktree add ... && cursor .	git gtr new feature --editor
Open in editor	cd ../repo-feature && cursor .	git gtr editor feature
Start AI tool	cd ../repo-feature && claude	git gtr ai feature
Copy config files	Manual copy/paste	Auto-copy via gtr.copy.include
Run build steps	Manual npm install && npm run build	Auto-run via gtr.hook.postCreate
List worktrees	git worktree list (shows paths)	git gtr list (shows branches + status)
Clean up	git worktree remove ../repo-feature	git gtr rm feature

TL;DR: git gtr wraps git worktree with quality-of-life features for modern development workflows (AI tools, editors, automation).

Features

• Simple commands - Create and manage worktrees with intuitive CLI
• Repository-scoped - Each repo has independent worktrees
• Configuration over flags - Set defaults once, use simple commands
• Editor integration - Open worktrees in Antigravity, Cursor, VS Code, Zed, and more
• AI tool support - Launch Aider, Claude Code, or other AI coding tools
• Smart file copying - Selectively copy configs/env files to new worktrees
• Hooks system - Run custom commands after create/remove
• Cross-platform - Works on macOS, Linux, and Windows (Git Bash)
• Shell completions - Tab completion for Bash, Zsh, and Fish

Requirements

• Git 2.17+ (for git worktree move/remove support)
• Bash 3.2+ (macOS ships 3.2; 4.0+ recommended for advanced features)

Commands

Commands accept branch names to identify worktrees. Use 1 to reference the main repo. Run git gtr help for full documentation.

git gtr new <branch> [options]

Create a new git worktree. Folder is named after the branch.

git gtr new my-feature                                                                   # Creates folder: my-feature
git gtr new hotfix --from v1.2.3                                                         # Create from specific ref
git gtr new variant-1 --from-current                                                     # Create from current branch
git gtr new feature/auth                                                                 # Creates folder: feature-auth
git gtr new feature/implement-user-authentication-with-oauth2-integration --folder auth  # Custom folder name
git gtr new feature-auth --name backend --force                                          # Same branch, custom name
git gtr new my-feature --name descriptive-variant                                        # Optional: custom name without --force

Options:

• --from <ref>: Create from specific ref
• --from-current: Create from current branch (useful for parallel variant work)
• --remote <name>: Remote used for default base refs
• --track <mode>: Tracking mode (auto|remote|local|none)
• --no-copy: Skip file copying
• --no-fetch: Skip git fetch
• --no-hooks: Skip post-create hooks
• --force: Allow same branch in multiple worktrees (requires --name or --folder)
• --name <suffix>: Custom folder name suffix (optional, required with --force)
• --folder <name>: Custom folder name (replaces default, useful for long branch names)
• --editor, -e: Open in editor after creation
• --ai, -a: Start AI tool after creation
• --yes: Non-interactive mode

git gtr editor <branch> [--editor <name>]

Open worktree in editor (uses gtr.editor.default or --editor flag).

git gtr editor my-feature                    # Uses configured editor
git gtr editor my-feature --editor vscode    # Override with vscode

git gtr ai <branch> [--ai <name>] [-- args...]

Start AI coding tool (uses gtr.ai.default or --ai flag).

git gtr ai my-feature                      # Uses configured AI tool
git gtr ai my-feature --ai codex          # Override with different tool
git gtr ai my-feature -- --model gpt-4    # Pass arguments to tool
git gtr ai 1                              # Use AI in main repo

git gtr go <branch>

Print worktree path for shell navigation.

cd "$(git gtr go my-feature)"    # Navigate by branch name
cd "$(git gtr go 1)"             # Navigate to main repo

Tip: For easier navigation, use git gtr init to enable gtr cd:

# Bash (add to ~/.bashrc)
_gtr_init="${XDG_CACHE_HOME:-$HOME/.cache}/gtr/init-gtr.bash"
[[ -f "$_gtr_init" ]] || eval "$(git gtr init bash)" || true
source "$_gtr_init" 2>/dev/null || true; unset _gtr_init

# Zsh (add to ~/.zshrc)
_gtr_init="${XDG_CACHE_HOME:-$HOME/.cache}/gtr/init-gtr.zsh"
[[ -f "$_gtr_init" ]] || eval "$(git gtr init zsh)" || true
source "$_gtr_init" 2>/dev/null || true; unset _gtr_init

# Fish (add to ~/.config/fish/config.fish)
set -l _gtr_init (test -n "$XDG_CACHE_HOME" && echo $XDG_CACHE_HOME || echo $HOME/.cache)/gtr/init-gtr.fish
test -f "$_gtr_init"; or git gtr init fish >/dev/null 2>&1
source "$_gtr_init" 2>/dev/null

# Then navigate with:
gtr new my-feature --cd  # Create and land in the new worktree
gtr cd                # Interactive worktree picker (requires fzf)
gtr cd my-feature
gtr cd 1

The cache generates on first run and refreshes the next time git gtr init <shell> runs. To force-regenerate: rm -rf ~/.cache/gtr

With fzf installed, gtr cd (no arguments) opens a command palette with git log preview and keybindings: ctrl-e editor, ctrl-a AI, ctrl-d delete, ctrl-y copy, ctrl-r refresh.

Note: If gtr conflicts with another command (e.g., GNU tr from coreutils), use --as to pick a different name:

eval "$(git gtr init zsh --as gwtr)"
gwtr cd my-feature

git gtr run <branch> <command...>

Execute command in worktree directory.

git gtr run my-feature npm test             # Run tests
git gtr run my-feature npm run dev          # Start dev server
git gtr run feature-auth git status         # Run git commands
git gtr run 1 npm run build                 # Run in main repo

git gtr rm <branch>... [options]

Remove worktree(s) by branch name.

git gtr rm my-feature                              # Remove one
git gtr rm feature-a feature-b                     # Remove multiple
git gtr rm my-feature --delete-branch --force      # Delete branch and force

Options: --delete-branch, --force, --yes

git gtr mv <old> <new> [--force] [--yes]

Rename worktree directory and branch together. Aliases: rename

git gtr mv feature-wip feature-auth      # Rename worktree and branch
git gtr mv old-name new-name --force     # Force rename locked worktree
git gtr mv old-name new-name --yes       # Skip confirmation

Options: --force, --yes

Note: Only renames the local branch. Remote branch remains unchanged.

git gtr copy <target>... [options] [-- <pattern>...]

Copy files from main repo to existing worktree(s). Useful for syncing env files after worktree creation.

git gtr copy my-feature                       # Uses gtr.copy.include patterns
git gtr copy my-feature -- ".env*"            # Explicit pattern
git gtr copy my-feature -- ".env*" "*.json"   # Multiple patterns
git gtr copy -a -- ".env*"                    # Copy to all worktrees
git gtr copy my-feature -n -- "**/.env*"      # Dry-run preview

Options:

• -n, --dry-run: Preview without copying
• -a, --all: Copy to all worktrees
• --from <source>: Copy from different worktree (default: main repo)

git gtr list [--porcelain]

List all worktrees. Use --porcelain for machine-readable output.

git gtr config {get|set|add|unset|list} <key> [value] [--global]

Manage configuration via git config.

git gtr config set gtr.editor.default cursor       # Set locally
git gtr config set gtr.ai.default claude --global  # Set globally
git gtr config get gtr.editor.default              # Get value
git gtr config list                                # List all gtr config

git gtr clean [options]

Remove worktrees: clean up empty directories, or remove those with merged PRs/MRs.

git gtr clean                                  # Remove empty worktree directories and prune
git gtr clean --merged                         # Remove worktrees for merged PRs/MRs
git gtr clean --merged --to main               # Only remove worktrees merged to main
git gtr clean --merged --dry-run               # Preview which worktrees would be removed
git gtr clean --merged --yes                   # Remove without confirmation prompts
git gtr clean --merged --force                 # Force-clean merged, ignoring local changes
git gtr clean --merged --force --yes           # Force-clean and auto-confirm

Options:

• --merged: Remove worktrees whose branches have merged PRs/MRs (also deletes the branch)
• --to <ref>: Limit --merged cleanup to PRs/MRs merged into the given base ref
• --dry-run, -n: Preview changes without removing
• --yes, -y: Non-interactive mode (skip confirmation prompts)
• --force, -f: Force removal even if worktree has uncommitted changes or untracked files

Note: The --merged mode auto-detects your hosting provider (GitHub or GitLab) from the origin remote URL and requires the corresponding CLI tool (gh or glab) to be installed and authenticated. For self-hosted instances, set the provider explicitly: git gtr config set gtr.provider gitlab.

Note: clean also detects registry entries that are locked but whose directories no longer exist (for example, a crashed agent session that deleted its worktree directory). git worktree prune skips locked entries by design, so these linger and keep their branches checked out. clean offers to unlock and prune them; --force or --yes confirms automatically.

git gtr trust

Review and approve executable commands defined in the repository's .gtrconfig file. Hooks and editor/AI defaults from .gtrconfig are not used until explicitly trusted — this prevents malicious contributors from injecting arbitrary shell commands via shared config files.

git gtr trust                              # Review and approve .gtrconfig commands

Trust is stored per repository path plus executable command definitions and must be re-approved if hooks or editor/AI defaults change. Hooks and defaults from your local git config (.git/config, ~/.gitconfig) are always trusted.

Other Commands

• git gtr doctor - Health check (verify git, editors, AI tools)
• git gtr adapter - List available editor & AI adapters
• git gtr version - Show version

Configuration

All configuration is stored via git config. For team settings, create a .gtrconfig file in your repository root.

Quick Setup

# Set your editor (antigravity, cursor, vscode, zed)
git gtr config set gtr.editor.default cursor

# Set your AI tool (aider, auggie, claude, codex, continue, copilot, cursor, gemini, opencode)
git gtr config set gtr.ai.default claude

# Override-backed adapters may include flags
git gtr config set gtr.editor.default "nano -w"
git gtr config set gtr.ai.default "claude --continue"

# Generic fallbacks may use other safe PATH commands
git gtr config set gtr.editor.default "code --wait"
git gtr config set gtr.ai.default "bunx @github/copilot@latest"

# Copy env files to new worktrees
git gtr config add gtr.copy.include "**/.env.example"

# Run setup after creating worktrees
git gtr config add gtr.hook.postCreate "npm install"

# Re-source environment after gtr cd or gtr new --cd (runs in current shell)
git gtr config add gtr.hook.postCd "source ./vars.sh"

# Disable color output (or use "always" to force it)
git gtr config set gtr.ui.color never

Team Configuration (.gtrconfig)

# .gtrconfig - commit this to share settings
[copy]
    include = **/.env.example
    exclude = **/.env
    includeDirs = node_modules
    excludeDirs = node_modules/.cache

[hooks]
    postCreate = npm install

[defaults]
    editor = cursor
    ai = claude
    remote = upstream

Command trust: Hooks and editor/AI defaults defined in .gtrconfig require explicit approval before they execute or select tools. Run git gtr trust after cloning a repository or when .gtrconfig command entries change. This protects against malicious command injection in shared repositories.

Adapter safety: Generic gtr.editor.default and gtr.ai.default values must resolve to safe PATH commands. Filesystem paths such as ./tool and shell wrapper forms such as sh -c ... are rejected. Override-backed adapters like claude, cursor, and nano may include additional flags, for example claude --continue or nano -w.

Configuration precedence (highest to lowest):

1. git config --local (.git/config) - personal overrides
2. .gtrconfig (repo root) - team defaults (hooks and editor/AI defaults require git gtr trust)
3. git config --global (~/.gitconfig) - user defaults

For complete configuration reference including all settings, hooks, file copying patterns, and environment variables, see docs/configuration.md

Shell Completions (Optional)

Homebrew installs native Bash, Zsh, and Fish completion files automatically. Use the commands below for manual setup when installing from source or when you want to load completions explicitly.

# Bash (~/.bashrc)
source <(git gtr completion bash)

# Zsh (~/.zshrc) - must be before compinit
eval "$(git gtr completion zsh)"

# Fish
mkdir -p ~/.config/fish/completions
git gtr completion fish > ~/.config/fish/completions/git-gtr.fish

For troubleshooting, see docs/configuration.md#shell-completions

Platform Support

Platform	Status	Notes
macOS	Full support	Ventura+ recommended
Linux	Full support	Ubuntu, Fedora, Arch, etc.
Windows	Git Bash or WSL	Native PowerShell not supported

Requires Git 2.17+ and Bash 3.2+.

For troubleshooting, platform-specific notes, and architecture details, see docs/troubleshooting.md

Advanced Usage

For advanced workflows including:

• Multiple worktrees on same branch (--force + --name)
• Parallel AI agent development patterns
• Custom workflow scripts (.gtr-setup.sh)
• CI/CD automation (non-interactive mode)
• Working with multiple repositories

See docs/advanced-usage.md

Contributing

Contributions welcome! Areas where help is appreciated:

• New editor adapters - JetBrains IDEs, Neovim, etc.
• New AI tool adapters - Codeium, etc.
• Bug reports - Platform-specific issues
• Documentation - Tutorials, examples, use cases

See CONTRIBUTING.md for guidelines and CODE_OF_CONDUCT.md for community standards.

License

This project is licensed under the Apache License 2.0.

---

Built to streamline parallel development workflows with git worktrees.

For questions or issues, open an issue.