git-worktree-runner
4
总安装量
2
周安装量
#48736
全站排名
安装命令
npx skills add https://github.com/thearyanag/git-worktree-runner --skill git-worktree-runner
Agent 安装分布
amp
2
opencode
2
kimi-cli
2
github-copilot
2
gemini-cli
2
Skill 文档
git-worktree-runner (gtr)
A portable CLI for managing git worktrees with editor and AI tool integration. Wraps git worktree with quality-of-life features for modern parallel development.
Installation
git clone https://github.com/coderabbitai/git-worktree-runner.git
cd git-worktree-runner
sudo ln -s "$(pwd)/bin/git-gtr" /usr/local/bin/git-gtr
Requires Git 2.5+ and Bash 3.2+. Shell completions available for Bash, Zsh, and Fish.
Core Workflow
cd ~/your-repo
git gtr config set gtr.editor.default cursor # one-time
git gtr config set gtr.ai.default claude # one-time
git gtr new my-feature # create worktree
git gtr editor my-feature # open in editor
git gtr ai my-feature # start AI tool
git gtr run my-feature npm test # run commands
git gtr rm my-feature # clean up
Use 1 to reference the main repo (e.g., git gtr ai 1).
Commands Reference
| Command | Purpose |
|---|---|
git gtr new <branch> [opts] |
Create worktree. Options: --from <ref>, --from-current, --track, --no-copy, --no-fetch, --force (requires --name), --name <suffix>, --yes |
git gtr editor <branch> |
Open in configured editor. Override: --editor <n> |
git gtr ai <branch> [-- args] |
Start AI tool. Override: --ai <n>. Pass args after -- |
git gtr go <branch> |
Print path. Use: cd "$(git gtr go my-feature)" |
git gtr run <branch> <cmd> |
Execute command in worktree directory |
git gtr rm <branch>... [opts] |
Remove worktree(s). Options: --delete-branch, --force, --yes |
git gtr list [--porcelain] |
List all worktrees |
git gtr config {get|set|add|unset} <key> [val] |
Manage config. Add --global for global scope |
git gtr doctor |
Health check |
git gtr adapter |
List available editor & AI adapters |
git gtr clean |
Remove stale worktrees |
Configuration
All config stored via git config. For full configuration details including worktree directory settings, file copying patterns, hooks, and advanced usage, read references/configuration.md.
Key Config Values
gtr.worktrees.dir # base directory for worktrees (default: <repo>-worktrees)
gtr.worktrees.prefix # folder prefix (default: "")
gtr.defaultBranch # default branch (default: auto-detect)
gtr.editor.default # editor: cursor, vscode, zed, none
gtr.ai.default # AI tool: claude, aider, codex, continue, cursor, gemini, opencode, none
gtr.copy.include # glob patterns for files to copy (multi-valued)
gtr.copy.exclude # glob patterns to exclude (multi-valued)
gtr.copy.includeDirs # directories to copy (e.g., node_modules)
gtr.copy.excludeDirs # directory patterns to exclude
gtr.hook.postCreate # commands to run after creation (multi-valued)
gtr.hook.postRemove # commands to run after removal (multi-valued)
Common Scenarios
Parallel AI agents on one feature:
git gtr new feature-auth
git gtr new feature-auth --force --name backend
git gtr new feature-auth --force --name frontend
git gtr ai feature-auth-backend -- --message "Implement API"
git gtr ai feature-auth-frontend -- --message "Build UI"
Node.js project setup:
git gtr config set gtr.editor.default cursor
git gtr config add gtr.copy.include "**/.env.example"
git gtr config add gtr.hook.postCreate "npm install"
git gtr config add gtr.hook.postCreate "npm run build"
Non-interactive automation (CI/scripts):
git gtr new ci-test --yes --no-copy
git gtr rm ci-test --yes --delete-branch
Troubleshooting
- Worktree creation fails: Run
git fetch originfirst. Check branch exists withgit branch -a | grep <branch>. Try--track remote. - Editor not opening: Verify command available (
command -v cursor). Check config:git gtr config get gtr.editor.default. - File copying issues: Check patterns:
git gtr config get gtr.copy.include. Test withfind . -path "<pattern>". - Health check: Run
git gtr doctorto verify git, editors, and AI tools are properly configured.
Platform Support
- macOS: Full support (Ventura+). GUI:
open, terminal: iTerm2/Terminal.app - Linux: Full support. GUI:
xdg-open, terminal: gnome-terminal/konsole - Windows: Git Bash or WSL required