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

Install:

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

Manual installation options

macOS (Apple Silicon with Homebrew):

ln -s "$(pwd)/bin/git-gtr" "$(brew --prefix)/bin/git-gtr"

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 ~/bin
ln -s "$(pwd)/bin/git-gtr" ~/bin/git-gtr
# Add to ~/.zshrc or ~/.bashrc if ~/bin is not in PATH:
# export PATH="$HOME/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 (alternative)
cd "$(git gtr go my-feature)"

# List all worktrees
git gtr list

# Remove when done
git gtr rm my-feature

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 && aider	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 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.5+ (for git worktree 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-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)
• --track <mode>: Tracking mode (auto|remote|local|none)
• --no-copy: Skip file copying
• --no-fetch: Skip git fetch
• --force: Allow same branch in multiple worktrees (requires --name)
• --name <suffix>: Custom folder name suffix (optional, required with --force)
• --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 aider          # Override with aider
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

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

Other Commands

• git gtr doctor - Health check (verify git, editors, AI tools)
• git gtr adapter - List available editor & AI adapters
• git gtr clean - Remove stale worktrees
• 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 (cursor, vscode, zed)
git gtr config set gtr.editor.default cursor

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

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

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

Configuration precedence (highest to lowest):

1. git config --local (.git/config) - personal overrides
2. .gtrconfig (repo root) - team defaults
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)

Enable tab completion for your shell:

Bash:

echo 'source /path/to/git-worktree-runner/completions/gtr.bash' >> ~/.bashrc

Zsh:

mkdir -p ~/.zsh/completions
cp /path/to/git-worktree-runner/completions/_git-gtr ~/.zsh/completions/
# Add to ~/.zshrc: fpath=(~/.zsh/completions $fpath) && autoload -Uz compinit && compinit
# Then: source ~/.zsh/completions/_git-gtr

Fish:

ln -s /path/to/git-worktree-runner/completions/git-gtr.fish ~/.config/fish/completions/

For detailed setup (bash-completion requirements, 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.5+ 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.