tomevault-io Git Worktree Runner (gtr)
Overview
This skill provides workflows for managing git worktrees using the git gtr CLI tool. Git worktrees enable working on multiple branches simultaneously in separate directories without stashing changes or switching branches.
Quick Start
To check if gtr is installed:
git gtr --version
If not installed, guide user through 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
Common Workflows
Create and Work on Feature Branch
Full lifecycle for feature development:
# 1. Create worktree for new feature
git gtr new feature-name
# 2. Open in editor (uses configured default)
git gtr editor feature-name
# 3. Launch AI tool in worktree (see note about nested Claude)
git gtr ai feature-name
# 4. Run commands in worktree
git gtr run feature-name npm test
git gtr run feature-name npm run build
# 5. When done, remove worktree
git gtr rm feature-name
Quick Parallel Development
For quick context switching between branches:
# List existing worktrees
git gtr list
# Create worktree from existing branch
git gtr new existing-branch
# Navigate to worktree (prints path - use quotes for spaces)
cd "$(git gtr go branch-name)"
# Or run commands directly
git gtr run branch-name git status
Multiple Worktrees Same Branch
For different aspects of the same feature:
git gtr new feature --force --name frontend
git gtr new feature --force --name backend
Non-Interactive/CI Usage
For automation scenarios:
git gtr new ci-test --yes --no-copy
git gtr rm ci-test --yes --delete-branch
Core Commands
| Command | Description |
|---|---|
git gtr new <branch> |
Create new worktree |
git gtr list |
List all worktrees |
git gtr editor <branch> |
Open worktree in editor |
git gtr ai <branch> |
Launch AI tool in worktree |
git gtr run <branch> <cmd> |
Execute command in worktree |
git gtr go <branch> |
Print worktree path |
git gtr rm <branch> |
Remove worktree |
git gtr copy <target> |
Sync files to worktree(s) |
git gtr config |
Manage configuration |
Configuration
Key settings via git gtr config set:
# Set default editor (cursor, vscode, zed)
git gtr config set gtr.editor.default cursor
# Set default AI tool (claude, aider, codex, continue, cursor)
git gtr config set gtr.ai.default claude
# Set worktrees directory
git gtr config set gtr.worktrees.dir ~/worktrees
# Set files to auto-copy on worktree creation
git gtr config set gtr.copy.include ".env*,*.local"
Hooks
Hooks run at worktree lifecycle events and receive environment variables:
REPO_ROOT- Repository root pathWORKTREE_PATH- Worktree directory locationBRANCH- Branch name
Configure hooks:
git gtr config set gtr.hook.postCreate "npm install"
git gtr config set gtr.hook.preRemove "npm run clean"
git gtr config set gtr.hook.postRemove "echo 'Cleaned up'"
File Copying
Copy files to worktrees:
# Copy specific patterns to one worktree (note the -- separator)
git gtr copy feature -- ".env*" "*.json"
# Copy to all worktrees
git gtr copy -a -- ".env*"
Reference
For detailed command options and configuration, see references/commands.md.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.