DOCSEARCHbyAlgolia
Submit Docs

git-worktree-runner

repository·main·Indexed 23 days ago

https://github.com/coderabbitai/git-worktree-runner

A tool to streamline the creation and management of git worktrees. It features automated file and directory copying for dependencies and environment files, integrated support for AI tools (such as Claude, Cursor, and Copilot), and team-shared configurations via .gtrconfig. The tool supports repository-scoped management, custom lifecycle hooks (postCreate, preRemove, postRemove, postCd), and non-interactive flags for CI/CD automation.

Tokens
15.9K
Snippets
49
Records
78
Agent score
81%

What's inside git-worktree-runner

  1. Understand configuration precedence in git-worktree-runner

    main

    Configuration is managed via git config, allowing for per-repository, global, or system-wide settings. Settings are applied based on the following precedence (highest to lowest):

    1. git config --local (.git/config) - Personal overrides
    2. .gtrconfig (at repository root) - Team-shared defaults
    3. git config --global (~/.gitconfig) - User-wide defaults
    4. git config --system (/etc/gitconfig) - System-wide defaults
    5. Environment variables
    6. Default values

  2. Understand Repository Scoping in git-worktree-runner

    main

    The git gtr tool is repository-scoped. This means each Git repository manages its own independent set of worktrees.

    • Worktree folders are named after their branch names.
    • To manage a different repository, use cd to navigate to that repository's root, then run git gtr commands.
    • Each repository's worktree configuration and list are isolated from others.

  3. Create multiple worktrees for the same branch

    main

    By default, Git prevents checking out the same branch in multiple worktrees. git gtr allows you to bypass this using the --force and --name flags. This is useful for parallel AI development or testing the same branch in different environments.

    Warning: Concurrent edits in multiple worktrees can cause conflicts. Only edit files in one worktree at a time and commit/stash changes frequently.

    Requirements: When using --force, you must provide a --name to distinguish the worktrees.

    # Create multiple worktrees for same branch with descriptive names
git gtr new feature-auth                          # Main worktree: feature-auth/
git gtr new feature-auth --force --name backend   # Creates: feature-auth-backend/
git gtr new feature-auth --force --name frontend  # Creates: feature-auth-frontend/
git gtr new feature-auth --force --name tests     # Creates: feature-auth-tests/

  4. Work with multiple branches simultaneously

    main

    You can use git gtr to manage multiple branches in separate worktrees for parallel tasks like feature development and PR reviews.

    # Create and enter a new worktree for a feature
git gtr new feature-a
git gtr editor feature-a

# Create and enter a new worktree for a PR review
git gtr new pr/123
git gtr editor pr/123

# Navigate back to the main branch (repo root)
# If shell integration (git gtr init) is enabled:
gtr cd 1
# If shell integration is NOT enabled:
cd "$(git gtr go 1)"
    # Terminal 1: Work on feature
git gtr new feature-a
git gtr editor feature-a

# Terminal 2: Review PR
git gtr new pr/123
git gtr editor pr/123

# Terminal 3: Navigate to main branch (repo root)
gtr cd 1                  # With shell integration (git gtr init)
cd "$(git gtr go 1)"     # Without shell integration

  5. Configure team-shared settings with .gtrconfig

    main

    Create a .gtrconfig file in your repository root to share settings with your team. This file uses the standard Git configuration format.

    Important Security Note: Hooks, editor defaults, and AI tool defaults defined in .gtrconfig are treated as executable commands. They are ignored by the tool until you explicitly approve them using git gtr trust. Any changes to these entries will require re-approval.

    # .gtrconfig - commit this file to share settings with your team

[copy]
    include = **/.env.example
    include = *.md
    exclude = **/.env

[copy]
    includeDirs = node_modules
    excludeDirs = node_modules/.cache

[hooks]
    postCreate = npm install
    postCreate = cp .env.example .env

[defaults]
    editor = cursor
    ai = claude
    remote = upstream

  6. Configure Git Worktree Runner Hooks

    main

    You can run custom commands during specific worktree lifecycle events using hooks. Hooks are configured via git gtr config add.

    Available Hooks:

    • postCreate: Runs after worktree creation. Use this for setup tasks like npm install or cargo build. This is multi-valued; commands run in the order they were added.
    • preRemove: Runs before worktree deletion. If this hook fails, the removal is aborted unless you use the --force flag. Use this for cleanup that requires directory access.
    • postRemove: Runs after worktree deletion. Useful for logging or notifications.
    • postCd: Runs after gtr cd or gtr new --cd changes the directory. Crucially, these run in your current shell, allowing them to modify environment variables (e.g., source ./vars.sh). They only work via shell integration, not raw git gtr commands.

    Available Environment Variables in Hooks:

    • REPO_ROOT: Repository root path.
    • WORKTREE_PATH: Worktree path.
    • BRANCH: Branch name.
    # Post-create hooks (multi-valued, run in order)
git gtr config add gtr.hook.postCreate "npm install"
git gtr config add gtr.hook.postCreate "npm run build"

# Pre-remove hooks (run before deletion, abort on failure)
git gtr config add gtr.hook.preRemove "npm run cleanup"

# Post-remove hooks
git gtr config add gtr.hook.postRemove "echo 'Cleaned up!'"

# Post-cd hooks (run after gtr cd or gtr new --cd, in current shell)
git gtr config add gtr.hook.postCd "source ./vars.sh"

  7. Copy files to new worktrees

    main

    To ensure worktrees are functional immediately, you can specify files to be copied from the main repository during creation. You can do this in two ways:

    1. Via Git Config: Use gtr.copy.include and gtr.copy.exclude with glob patterns.
    2. Via .worktreeinclude file: Create a file named .worktreeinclude in your repository root. Use .gitignore-style syntax (one pattern per line). Patterns in this file are merged with gtr.copy.include settings.

    Security Tip: Always exclude production secrets (e.g., **/.env.production) using gtr.copy.exclude.

    # Add patterns to copy via CLI
git gtr config add gtr.copy.include "**/.env.example"
git gtr config add gtr.copy.include "*.md"

# Exclude patterns
git gtr config add gtr.copy.exclude "**/.env"

    Example .worktreeinclude file

    # .worktreeinclude - files to copy to new worktrees
**/.env.example
**/CLAUDE.md
*.config.js

  8. Automate project configuration with .gtr-setup.sh

    main

    You can create a .gtr-setup.sh script in your repository root to automate the configuration of git gtr settings, file copying, and post-creation hooks for your team.

    #!/bin/sh
# .gtr-setup.sh - Project-specific git gtr configuration

git gtr config set gtr.worktrees.prefix "dev-"
git gtr config set gtr.editor.default cursor

# Copy configs
git gtr config add gtr.copy.include ".env.example"
git gtr config add gtr.copy.include "docker-compose.yml"

# Setup hooks
git gtr config add gtr.hook.postCreate "docker-compose up -d db"
git gtr config add gtr.hook.postCreate "npm install"
git gtr config add gtr.hook.postCreate "npm run db:migrate"

# Run the script
sh .gtr-setup.sh

  9. Copy dependency directories to speed up worktree creation

    main

    To avoid long installation times (like npm install or pip install) when creating new worktrees, you can copy entire dependency directories using gtr.copy.includeDirs and gtr.copy.excludeDirs.

    Common Use Cases:

    • JS/TS: node_modules
    • Python: .venv or venv
    • PHP: vendor
    • Go: .cache or bin directories

    Warning: Dependency directories may contain sensitive files or tokens. Use gtr.copy.excludeDirs to exclude specific subdirectories (e.g., node_modules/.cache) to maintain security.

    # Copy dependency directories
git gtr config add gtr.copy.includeDirs "node_modules"
git gtr config add gtr.copy.includeDirs ".venv"

# Exclude specific nested directories
git gtr config add gtr.copy.excludeDirs "node_modules/.cache"

# Exclude using wildcards
gtr.copy.excludeDirs "node_modules/.*"
gtr.copy.excludeDirs "*/.cache"

  10. Set up shell integration for the 'cd' command

    main

    The cd command (used to change your shell's directory to a worktree) cannot work in a standard subprocess. To use it, you must first perform shell integration. Run the following command to see the setup instructions:

    git gtr help init

    Once integrated, you can use:

    gtr cd [<branch>]

  11. Configure and use AI tools

    main

    You can set a default AI tool to use with git gtr ai.

    Supported Tools: aider, auggie, claude, codex, continue, copilot, cursor, gemini, opencode.

    To use the tool, set it via config and then run git gtr ai <task>.

    # Set default AI tool for this repo
git gtr config set gtr.ai.default claude

# Or set globally for all repos
git gtr config set gtr.ai.default claude --global

# Use the tool
git gtr ai my-feature

# Pass arguments to the tool
git gtr ai my-feature -- --plan "refactor auth"

  12. Debug and Get Help with git-worktree-runner

    main

    If you encounter issues that are not covered in the troubleshooting guide, use these diagnostic tools:

    1. Run the doctor command: This checks your environment setup.
      git gtr doctor
    2. Enable Debug Mode: Prefix your command with bash -x to see the execution trace.
      bash -x git gtr <command>

    When reporting issues, please include your OS version, Git version (git --version), Bash version (bash --version), the command executed, and the error message.