{"id":46506801,"url":"https://github.com/coderabbitai/git-worktree-runner","last_synced_at":"2026-04-01T18:47:02.941Z","repository":{"id":324302734,"uuid":"1034104789","full_name":"coderabbitai/git-worktree-runner","owner":"coderabbitai","description":"Bash-based Git worktree manager with editor and AI tool integration. Automates per-branch worktree creation, configuration copying, dependency installation, and workspace setup for efficient parallel development.","archived":false,"fork":false,"pushed_at":"2026-03-18T23:51:05.000Z","size":350,"stargazers_count":1465,"open_issues_count":1,"forks_count":77,"subscribers_count":8,"default_branch":"main","last_synced_at":"2026-03-19T12:52:11.377Z","etag":null,"topics":["git","git-worktree"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/coderabbitai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-08-07T21:13:33.000Z","updated_at":"2026-03-19T11:26:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/coderabbitai/git-worktree-runner","commit_stats":null,"previous_names":["coderabbitai/git-worktree-runner"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/coderabbitai/git-worktree-runner","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coderabbitai%2Fgit-worktree-runner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coderabbitai%2Fgit-worktree-runner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coderabbitai%2Fgit-worktree-runner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coderabbitai%2Fgit-worktree-runner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/coderabbitai","download_url":"https://codeload.github.com/coderabbitai/git-worktree-runner/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coderabbitai%2Fgit-worktree-runner/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31290947,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["git","git-worktree"],"created_at":"2026-03-06T15:01:46.456Z","updated_at":"2026-04-01T18:47:02.934Z","avatar_url":"https://github.com/coderabbitai.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gtr - Git Worktree Runner\n\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE.txt)\n[![Bash](https://img.shields.io/badge/Bash-3.2%2B-green.svg)](https://www.gnu.org/software/bash/)\n[![Git](https://img.shields.io/badge/Git-2.17%2B-orange.svg)](https://git-scm.com/)\n[![Platform](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey.svg)](#platform-support)\n\n\u003e A portable, cross-platform CLI for managing git worktrees with ease\n\n![4 AI agents working in parallel across different worktrees](docs/assets/demo-parallel.png)\n\n## Table of Contents\n\n- [What are git worktrees?](#what-are-git-worktrees)\n- [Quick Start](#quick-start)\n- [Why gtr?](#why-gtr)\n- [Features](#features)\n- [Requirements](#requirements)\n- [Commands](#commands)\n- [Configuration](#configuration)\n- [Shell Completions](#shell-completions-optional)\n- [Platform Support](#platform-support)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## What are git worktrees?\n\n**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.\n\n**The Problem:** Everyone's using git worktrees wrong (or not at all):\n\n- Constantly stashing/switching branches disrupts flow\n- Running tests on main while working on features requires manual copying\n- Reviewing PRs means stopping current work\n- **Parallel AI agents on different branches?** Nearly impossible without worktrees\n\n**Why people sleep on worktrees:** The DX is terrible. `git worktree add ../my-project-feature feature` is verbose, manual, and error-prone.\n\n**Enter gtr:** Simple commands, AI tool integration, automatic setup, and built for modern parallel development workflows.\n\n## Quick Start\n\n**Homebrew (macOS):**\n\n```bash\nbrew tap coderabbitai/tap\nbrew install git-gtr\n```\n\n**Script installer (macOS / Linux):**\n\n```bash\ngit clone https://github.com/coderabbitai/git-worktree-runner.git\ncd git-worktree-runner\n./install.sh\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eOther installation options\u003c/b\u003e\u003c/summary\u003e\n\n**macOS (Intel) / Linux:**\n\n```bash\nsudo mkdir -p /usr/local/bin\nsudo ln -s \"$(pwd)/bin/git-gtr\" /usr/local/bin/git-gtr\n```\n\n**User-local (no sudo required):**\n\n```bash\nmkdir -p ~/.local/bin\nln -s \"$(pwd)/bin/git-gtr\" ~/.local/bin/git-gtr\n# Add to ~/.zshrc or ~/.bashrc if ~/.local/bin is not in PATH:\n# export PATH=\"$HOME/.local/bin:$PATH\"\n```\n\n\u003c/details\u003e\n\n**Usage:**\n\n```bash\n# Navigate to your git repo\ncd ~/GitHub/my-project\n\n# One-time setup (per repository)\ngit gtr config set gtr.editor.default cursor\ngit gtr config set gtr.ai.default claude\n\n# Daily workflow\ngit gtr new my-feature          # Create worktree folder: my-feature\ngit gtr new my-feature --editor # Create and open in editor\ngit gtr new my-feature --ai     # Create and start AI tool\ngit gtr new my-feature -e -a    # Create, open editor, then start AI\ngit gtr editor my-feature       # Open in cursor\ngit gtr ai my-feature           # Start claude\n\n# Run commands in worktree\ngit gtr run my-feature npm test # Run tests\n\n# Navigate to worktree\ngtr new my-feature --cd         # Create and cd (requires shell integration)\ngtr cd                          # Interactive picker (requires fzf + shell integration)\ngtr cd my-feature               # Requires shell integration (see below)\ncd \"$(git gtr go my-feature)\"   # Alternative without shell integration\n\n# List all worktrees\ngit gtr list\n\n# Remove when done\ngit gtr rm my-feature\n\n# Or remove all worktrees with merged PRs/MRs (requires gh or glab CLI)\ngit gtr clean --merged\n```\n\n## Why gtr?\n\nWhile `git worktree` is powerful, it's verbose and manual. `git gtr` adds quality-of-life features for modern development:\n\n| Task              | With `git worktree`                        | With `git gtr`                           |\n| ----------------- | ------------------------------------------ | ---------------------------------------- |\n| Create worktree   | `git worktree add ../repo-feature feature` | `git gtr new feature`                    |\n| Create + open     | `git worktree add ... \u0026\u0026 cursor .`         | `git gtr new feature --editor`           |\n| Open in editor    | `cd ../repo-feature \u0026\u0026 cursor .`           | `git gtr editor feature`                 |\n| Start AI tool     | `cd ../repo-feature \u0026\u0026 claude`             | `git gtr ai feature`                     |\n| Copy config files | Manual copy/paste                          | Auto-copy via `gtr.copy.include`         |\n| Run build steps   | Manual `npm install \u0026\u0026 npm run build`      | Auto-run via `gtr.hook.postCreate`       |\n| List worktrees    | `git worktree list` (shows paths)          | `git gtr list` (shows branches + status) |\n| Clean up          | `git worktree remove ../repo-feature`      | `git gtr rm feature`                     |\n\n**TL;DR:** `git gtr` wraps `git worktree` with quality-of-life features for modern development workflows (AI tools, editors, automation).\n\n## Features\n\n- **Simple commands** - Create and manage worktrees with intuitive CLI\n- **Repository-scoped** - Each repo has independent worktrees\n- **Configuration over flags** - Set defaults once, use simple commands\n- **Editor integration** - Open worktrees in Antigravity, Cursor, VS Code, Zed, and more\n- **AI tool support** - Launch Aider, Claude Code, or other AI coding tools\n- **Smart file copying** - Selectively copy configs/env files to new worktrees\n- **Hooks system** - Run custom commands after create/remove\n- **Cross-platform** - Works on macOS, Linux, and Windows (Git Bash)\n- **Shell completions** - Tab completion for Bash, Zsh, and Fish\n\n## Requirements\n\n- **Git** 2.17+ (for `git worktree move/remove` support)\n- **Bash** 3.2+ (macOS ships 3.2; 4.0+ recommended for advanced features)\n\n## Commands\n\nCommands accept branch names to identify worktrees. Use `1` to reference the main repo.\nRun `git gtr help` for full documentation.\n\n### `git gtr new \u003cbranch\u003e [options]`\n\nCreate a new git worktree. Folder is named after the branch.\n\n```bash\ngit gtr new my-feature                                                                   # Creates folder: my-feature\ngit gtr new hotfix --from v1.2.3                                                         # Create from specific ref\ngit gtr new variant-1 --from-current                                                     # Create from current branch\ngit gtr new feature/auth                                                                 # Creates folder: feature-auth\ngit gtr new feature/implement-user-authentication-with-oauth2-integration --folder auth  # Custom folder name\ngit gtr new feature-auth --name backend --force                                          # Same branch, custom name\ngit gtr new my-feature --name descriptive-variant                                        # Optional: custom name without --force\n```\n\n**Options:**\n\n- `--from \u003cref\u003e`: Create from specific ref\n- `--from-current`: Create from current branch (useful for parallel variant work)\n- `--track \u003cmode\u003e`: Tracking mode (auto|remote|local|none)\n- `--no-copy`: Skip file copying\n- `--no-fetch`: Skip git fetch\n- `--no-hooks`: Skip post-create hooks\n- `--force`: Allow same branch in multiple worktrees (**requires --name or --folder**)\n- `--name \u003csuffix\u003e`: Custom folder name suffix (optional, required with --force)\n- `--folder \u003cname\u003e`: Custom folder name (replaces default, useful for long branch names)\n- `--editor`, `-e`: Open in editor after creation\n- `--ai`, `-a`: Start AI tool after creation\n- `--yes`: Non-interactive mode\n\n### `git gtr editor \u003cbranch\u003e [--editor \u003cname\u003e]`\n\nOpen worktree in editor (uses `gtr.editor.default` or `--editor` flag).\n\n```bash\ngit gtr editor my-feature                    # Uses configured editor\ngit gtr editor my-feature --editor vscode    # Override with vscode\n```\n\n### `git gtr ai \u003cbranch\u003e [--ai \u003cname\u003e] [-- args...]`\n\nStart AI coding tool (uses `gtr.ai.default` or `--ai` flag).\n\n```bash\ngit gtr ai my-feature                      # Uses configured AI tool\ngit gtr ai my-feature --ai codex          # Override with different tool\ngit gtr ai my-feature -- --model gpt-4    # Pass arguments to tool\ngit gtr ai 1                              # Use AI in main repo\n```\n\n### `git gtr go \u003cbranch\u003e`\n\nPrint worktree path for shell navigation.\n\n```bash\ncd \"$(git gtr go my-feature)\"    # Navigate by branch name\ncd \"$(git gtr go 1)\"             # Navigate to main repo\n```\n\n**Tip:** For easier navigation, use `git gtr init` to enable `gtr cd`:\n\n```bash\n# Bash (add to ~/.bashrc)\n_gtr_init=\"${XDG_CACHE_HOME:-$HOME/.cache}/gtr/init-gtr.bash\"\n[[ -f \"$_gtr_init\" ]] || eval \"$(git gtr init bash)\" || true\nsource \"$_gtr_init\" 2\u003e/dev/null || true; unset _gtr_init\n\n# Zsh (add to ~/.zshrc)\n_gtr_init=\"${XDG_CACHE_HOME:-$HOME/.cache}/gtr/init-gtr.zsh\"\n[[ -f \"$_gtr_init\" ]] || eval \"$(git gtr init zsh)\" || true\nsource \"$_gtr_init\" 2\u003e/dev/null || true; unset _gtr_init\n\n# Fish (add to ~/.config/fish/config.fish)\nset -l _gtr_init (test -n \"$XDG_CACHE_HOME\" \u0026\u0026 echo $XDG_CACHE_HOME || echo $HOME/.cache)/gtr/init-gtr.fish\ntest -f \"$_gtr_init\"; or git gtr init fish \u003e/dev/null 2\u003e\u00261\nsource \"$_gtr_init\" 2\u003e/dev/null\n\n# Then navigate with:\ngtr new my-feature --cd  # Create and land in the new worktree\ngtr cd                # Interactive worktree picker (requires fzf)\ngtr cd my-feature\ngtr cd 1\n```\n\nThe cache generates on first run and refreshes the next time `git gtr init \u003cshell\u003e` runs. To force-regenerate: `rm -rf ~/.cache/gtr`\n\nWith [fzf](https://github.com/junegunn/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.\n\n\u003e **Note:** If `gtr` conflicts with another command (e.g., GNU `tr` from coreutils), use `--as` to pick a different name:\n\u003e\n\u003e ```bash\n\u003e eval \"$(git gtr init zsh --as gwtr)\"\n\u003e gwtr cd my-feature\n\u003e ```\n\n### `git gtr run \u003cbranch\u003e \u003ccommand...\u003e`\n\nExecute command in worktree directory.\n\n```bash\ngit gtr run my-feature npm test             # Run tests\ngit gtr run my-feature npm run dev          # Start dev server\ngit gtr run feature-auth git status         # Run git commands\ngit gtr run 1 npm run build                 # Run in main repo\n```\n\n### `git gtr rm \u003cbranch\u003e... [options]`\n\nRemove worktree(s) by branch name.\n\n```bash\ngit gtr rm my-feature                              # Remove one\ngit gtr rm feature-a feature-b                     # Remove multiple\ngit gtr rm my-feature --delete-branch --force      # Delete branch and force\n```\n\n**Options:** `--delete-branch`, `--force`, `--yes`\n\n### `git gtr mv \u003cold\u003e \u003cnew\u003e [--force] [--yes]`\n\nRename worktree directory and branch together. Aliases: `rename`\n\n```bash\ngit gtr mv feature-wip feature-auth      # Rename worktree and branch\ngit gtr mv old-name new-name --force     # Force rename locked worktree\ngit gtr mv old-name new-name --yes       # Skip confirmation\n```\n\n**Options:** `--force`, `--yes`\n\n**Note:** Only renames the local branch. Remote branch remains unchanged.\n\n### `git gtr copy \u003ctarget\u003e... [options] [-- \u003cpattern\u003e...]`\n\nCopy files from main repo to existing worktree(s). Useful for syncing env files after worktree creation.\n\n```bash\ngit gtr copy my-feature                       # Uses gtr.copy.include patterns\ngit gtr copy my-feature -- \".env*\"            # Explicit pattern\ngit gtr copy my-feature -- \".env*\" \"*.json\"   # Multiple patterns\ngit gtr copy -a -- \".env*\"                    # Copy to all worktrees\ngit gtr copy my-feature -n -- \"**/.env*\"      # Dry-run preview\n```\n\n**Options:**\n\n- `-n, --dry-run`: Preview without copying\n- `-a, --all`: Copy to all worktrees\n- `--from \u003csource\u003e`: Copy from different worktree (default: main repo)\n\n### `git gtr list [--porcelain]`\n\nList all worktrees. Use `--porcelain` for machine-readable output.\n\n### `git gtr config {get|set|add|unset|list} \u003ckey\u003e [value] [--global]`\n\nManage configuration via git config.\n\n```bash\ngit gtr config set gtr.editor.default cursor       # Set locally\ngit gtr config set gtr.ai.default claude --global  # Set globally\ngit gtr config get gtr.editor.default              # Get value\ngit gtr config list                                # List all gtr config\n```\n\n### `git gtr clean [options]`\n\nRemove worktrees: clean up empty directories, or remove those with merged PRs/MRs.\n\n```bash\ngit gtr clean                                  # Remove empty worktree directories and prune\ngit gtr clean --merged                         # Remove worktrees for merged PRs/MRs\ngit gtr clean --merged --dry-run               # Preview which worktrees would be removed\ngit gtr clean --merged --yes                   # Remove without confirmation prompts\ngit gtr clean --merged --force                 # Force-clean merged, ignoring local changes\ngit gtr clean --merged --force --yes           # Force-clean and auto-confirm\n```\n\n**Options:**\n\n- `--merged`: Remove worktrees whose branches have merged PRs/MRs (also deletes the branch)\n- `--dry-run`, `-n`: Preview changes without removing\n- `--yes`, `-y`: Non-interactive mode (skip confirmation prompts)\n- `--force`, `-f`: Force removal even if worktree has uncommitted changes or untracked files\n\n**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`.\n\n### Other Commands\n\n- `git gtr doctor` - Health check (verify git, editors, AI tools)\n- `git gtr adapter` - List available editor \u0026 AI adapters\n- `git gtr version` - Show version\n\n## Configuration\n\nAll configuration is stored via `git config`. For team settings, create a `.gtrconfig` file in your repository root.\n\n### Quick Setup\n\n```bash\n# Set your editor (antigravity, cursor, vscode, zed)\ngit gtr config set gtr.editor.default cursor\n\n# Set your AI tool (aider, auggie, claude, codex, continue, copilot, cursor, gemini, opencode)\ngit gtr config set gtr.ai.default claude\n\n# Copy env files to new worktrees\ngit gtr config add gtr.copy.include \"**/.env.example\"\n\n# Run setup after creating worktrees\ngit gtr config add gtr.hook.postCreate \"npm install\"\n\n# Re-source environment after gtr cd or gtr new --cd (runs in current shell)\ngit gtr config add gtr.hook.postCd \"source ./vars.sh\"\n\n# Disable color output (or use \"always\" to force it)\ngit gtr config set gtr.ui.color never\n```\n\n### Team Configuration (.gtrconfig)\n\n```gitconfig\n# .gtrconfig - commit this to share settings\n[copy]\n    include = **/.env.example\n    exclude = **/.env\n    includeDirs = node_modules\n    excludeDirs = node_modules/.cache\n\n[hooks]\n    postCreate = npm install\n\n[defaults]\n    editor = cursor\n    ai = claude\n```\n\n**Configuration precedence** (highest to lowest):\n\n1. `git config --local` (`.git/config`) - personal overrides\n2. `.gtrconfig` (repo root) - team defaults\n3. `git config --global` (`~/.gitconfig`) - user defaults\n\n\u003e For complete configuration reference including all settings, hooks, file copying patterns, and environment variables, see [docs/configuration.md](docs/configuration.md)\n\n## Shell Completions (Optional)\n\nHomebrew installs native Bash, Zsh, and Fish completion files automatically.\nUse the commands below for manual setup when installing from source or when you\nwant to load completions explicitly.\n\n```bash\n# Bash (~/.bashrc)\nsource \u003c(git gtr completion bash)\n\n# Zsh (~/.zshrc) - must be before compinit\neval \"$(git gtr completion zsh)\"\n\n# Fish\nmkdir -p ~/.config/fish/completions\ngit gtr completion fish \u003e ~/.config/fish/completions/git-gtr.fish\n```\n\n\u003e For troubleshooting, see [docs/configuration.md#shell-completions](docs/configuration.md#shell-completions)\n\n## Platform Support\n\n| Platform    | Status          | Notes                           |\n| ----------- | --------------- | ------------------------------- |\n| **macOS**   | Full support    | Ventura+ recommended            |\n| **Linux**   | Full support    | Ubuntu, Fedora, Arch, etc.      |\n| **Windows** | Git Bash or WSL | Native PowerShell not supported |\n\nRequires Git 2.17+ and Bash 3.2+.\n\n\u003e For troubleshooting, platform-specific notes, and architecture details, see [docs/troubleshooting.md](docs/troubleshooting.md)\n\n## Advanced Usage\n\nFor advanced workflows including:\n\n- **Multiple worktrees on same branch** (`--force` + `--name`)\n- **Parallel AI agent development** patterns\n- **Custom workflow scripts** (`.gtr-setup.sh`)\n- **CI/CD automation** (non-interactive mode)\n- **Working with multiple repositories**\n\nSee [docs/advanced-usage.md](docs/advanced-usage.md)\n\n## Contributing\n\nContributions welcome! Areas where help is appreciated:\n\n- **New editor adapters** - JetBrains IDEs, Neovim, etc.\n- **New AI tool adapters** - Codeium, etc.\n- **Bug reports** - Platform-specific issues\n- **Documentation** - Tutorials, examples, use cases\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community standards.\n\n## License\n\nThis project is licensed under the [Apache License 2.0](LICENSE.txt).\n\n---\n\nBuilt to streamline parallel development workflows with git worktrees.\n\nFor questions or issues, [open an issue](https://github.com/coderabbitai/git-worktree-runner/issues).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoderabbitai%2Fgit-worktree-runner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcoderabbitai%2Fgit-worktree-runner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoderabbitai%2Fgit-worktree-runner/lists"}