git-worktree-runner

# Git Worktree Runner (gtr) git-worktree-runner (gtr) is a CLI tool that wraps `git worktree` with quality-of-life features for modern development workflows including editor and AI tool integration. ## Quick Start ```bash # Create a new worktree git gtr new feature-branch # Create from a remote branch git gtr new my-branch --from origin/feature-branch # Open editor in the worktree git gtr editor feature-branch # Start AI tool (claude, codex, etc.) in the worktree git gtr ai feature-branch # Remove a worktree git gtr rm feature-branch ``` ## Commands ### Creating Worktrees ```bash # Create a new worktree with a new branch git gtr new feature-name # Create from a specific ref (remote branch, tag, commit) git gtr new my-branch --from origin/main git gtr new hotfix --from v1.2.3 # Create and immediately open in editor git gtr new feature -e # Create and immediately start AI tool git gtr new feature -a # Create with both editor and AI tool git gtr new feature -e -a ``` ### Opening Editor / AI Tool ```bash # Open the configured editor for a worktree git gtr editor feature-branch # Start configured AI tool in a worktree git gtr ai feature-branch ``` ### Running Commands ```bash # Run an arbitrary command in a worktree git gtr run feature-branch npm test git gtr run feature-branch pnpm build ``` ### Navigation ```bash # Navigate to a worktree directory cd "$(git gtr go feature-branch)" ``` ### Listing and Managing ```bash # List all worktrees git gtr list # Remove a worktree git gtr rm feature-branch # Rename a worktree git gtr mv old-name new-name ``` ## Configuration ```bash # Set default editor (cursor, vscode, zed, etc.) git gtr config set gtr.editor.default cursor # Set default AI tool (claude, codex, opencode, aider, etc.) git gtr config set gtr.ai.default claude # Configure files to copy into new worktrees git gtr config add gtr.copy.include "**/.env" git gtr config add gtr.copy.include "**/.env.local" git gtr config add gtr.copy.include "**/.env.example" # View current configuration git gtr config list ``` ## Example: Parallel AI Development ```bash # Create isolated worktrees for parallel AI agents git gtr new feature-auth --from origin/main git gtr new feature-api --from origin/main git gtr new bugfix-login --from origin/main # Start AI tools in each worktree git gtr ai feature-auth git gtr ai feature-api git gtr ai bugfix-login # Check status of all worktrees git gtr list # Clean up when done git gtr rm feature-auth git gtr rm feature-api git gtr rm bugfix-login ``` ## Example: PR Review in Isolated Worktree ```bash # Create a worktree from PR branch git gtr new review-pr-123 --from origin/pr-branch # Open in editor to review git gtr editor review-pr-123 # Run tests in isolation git gtr run review-pr-123 pnpm test # Clean up after review git gtr rm review-pr-123 ``` ## Example: Hotfix While Working on Feature ```bash # Current work is on feature-branch, need to do a hotfix git gtr new hotfix-critical --from origin/main # Open editor for the hotfix git gtr new hotfix-critical -e # After hotfix is done, remove the worktree git gtr rm hotfix-critical # Back to feature-branch work without context switching ``` ## Example: Checkout a Fork PR into Worktree For PRs from forked repositories, the branch is not on `origin`. Use GitHub's `refs/pull/<number>/head` ref to fetch it. ### Procedure Given a PR number or URL: 1. **Get PR metadata** ```bash gh pr view <PR_NUMBER> --json headRefName,isCrossRepository ``` 2. **Check for existing worktree** with the same branch name ```bash git worktree list ``` If it exists, remove it first: `git gtr rm <branch>` 3. **Fetch the PR ref** into a local branch (use `--force` to handle diverged history from force-pushes) ```bash git fetch origin pull/<PR_NUMBER>/head:<BRANCH_NAME> --force ``` 4. **Create the worktree** with `--track local` since it's a local-only branch ```bash git gtr new <BRANCH_NAME> --track local ``` 5. **Verify** ```bash git gtr list ``` ### Full example (PR #1223 from a fork) ```bash gh pr view 1223 --json headRefName,isCrossRepository git fetch origin pull/1223/head:fix/comprehensive-file-formats-docs --force git gtr new fix/comprehensive-file-formats-docs --track local git gtr list ``` ### Shortening long branch names ```bash git fetch origin pull/1223/head:pr-1223 --force git gtr new pr-1223 --track local ``` ### Common errors - **"refusing to fetch into branch checked out at..."**: A worktree with that branch exists. `git gtr rm <branch>` first. - **"non-fast-forward" rejected**: Local branch diverged. Add `--force` to the fetch. - **Both errors**: Remove the worktree first, then fetch with `--force`.