Configuration Reference

September 14, 2026 · View on GitHub

Complete configuration guide for git-worktree-runner

Back to README | Advanced Usage | Troubleshooting

Configuration Sources
Team Configuration (.gtrconfig)
Worktree Settings
Provider Settings
Editor Settings
AI Tool Settings
File Copying
Directory Copying
Hooks
UI Settings
Shell Completions
Configuration Examples
Environment Variables

Configuration Sources

All configuration is stored via git config, making it easy to manage per-repository or globally. You can also use a .gtrconfig file for team-shared settings.

Configuration precedence (highest to lowest):

git config --local (.git/config) - personal overrides
.gtrconfig (repo root) - team defaults
git config --global (~/.gitconfig) - user defaults
git config --system (/etc/gitconfig) - system defaults
Environment variables
Default values

Team Configuration (.gtrconfig)

Create a .gtrconfig file in your repository root to share configuration across your team:

# .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

Tip

See templates/.gtrconfig.example for a complete example with all available settings.

Important

Hooks and editor/AI defaults from .gtrconfig are executable command entries. They are ignored until you review them with git gtr trust; changing those entries requires re-approval.

Worktree Settings

# Base directory for worktrees
# Default: <repo-name>-worktrees (sibling to repo)
# Supports: absolute paths, repo-relative paths, tilde expansion
gtr.worktrees.dir = <path>

# Examples:
# Absolute path
gtr.worktrees.dir = /Users/you/all-worktrees/my-project

# Repo-relative (inside repository - requires .gitignore entry)
gtr.worktrees.dir = .worktrees

# Home directory (tilde expansion)
gtr.worktrees.dir = ~/worktrees/my-project

# Folder prefix (default: "")
gtr.worktrees.prefix = dev-

# Default branch (default: auto-detect)
gtr.defaultBranch = main

# Default remote for fetches, tracking, and default base refs (default: origin)
gtr.defaultRemote = upstream

Important

If storing worktrees inside the repository, add the directory to .gitignore.

echo "/.worktrees/" >> .gitignore

Sparse-Checkout Settings

If the worktree you branch from uses sparse-checkout (e.g. a slice of a large monorepo), gtr can give the new worktree the same narrowed working tree instead of an expensive full checkout.

# Inherit sparse-checkout from the base worktree (default: true)
gtr.sparse.inherit = true

On Git 2.36+, git gtr new looks at the worktree holding the base ref (the --from target, falling back to the current worktree). If that worktree has valid sparse-checkout settings, gtr runs worktree creation from that source so Git copies its patterns and per-worktree config before checkout. The full tree is never materialized. Git 2.17–2.35 retains full-checkout behavior; explicit --sparse requests print a version warning.

Per-command overrides:

# Force inheritance even if gtr.sparse.inherit is off
git gtr new feature-xyz --from my-app --sparse

# Force a full checkout even if gtr.sparse.inherit is on
git gtr new feature-xyz --from my-app --no-sparse

Note

Sparse-checkout is stored per-worktree, not per-branch. "Inherit from my-app" means inherit the live sparse settings and worktree-specific Git config of the my-app worktree. Ambiguous duplicate-branch worktrees fall back to a full checkout instead of choosing a source arbitrarily.

Provider Settings

The clean --merged and clean --closed commands auto-detect your hosting provider from the origin remote URL (github.com → GitHub, gitlab.com → GitLab). For self-hosted instances, set the provider explicitly:

# Override auto-detected hosting provider (github or gitlab)
gtr.provider = gitlab

Setup:

# Self-hosted GitLab
git gtr config set gtr.provider gitlab

# Self-hosted GitHub Enterprise
git gtr config set gtr.provider github

Required CLI tools:

Provider	CLI Tool	Install
GitHub	`gh`	cli.github.com
GitLab	`glab`	gitlab.com/gitlab-org/cli

Editor Settings

# Default editor: antigravity, cursor, vscode, zed, or none
gtr.editor.default = cursor

# Workspace file for VS Code/Cursor/Antigravity (relative path from worktree root)
# If set, opens the workspace file instead of the folder
# If not set, auto-detects *.code-workspace files in worktree root
# Set to "none" to disable workspace lookup entirely
gtr.editor.workspace = project.code-workspace

Setup editors:

Antigravity: Install from antigravity.google, with the agy-ide command available
Cursor: Install from cursor.com, enable shell command
VS Code: Install from code.visualstudio.com, enable code command
Zed: Install from zed.dev, zed command available automatically

Workspace files:

VS Code, Cursor, and Antigravity support .code-workspace files for multi-root workspaces, custom settings, and recommended extensions. When opening a worktree:

If gtr.editor.workspace is set to a path, opens that file (relative to worktree root)
If set to none, disables workspace lookup (always opens folder)
Otherwise, auto-detects any *.code-workspace file in the worktree root
Falls back to opening the folder if no workspace file is found

AI Tool Settings

# Default AI tool: none (or antigravity, aider, auggie, claude, codex, copilot, cursor, gemini, opencode)
gtr.ai.default = none

Built-in AI Tool Adapters:

Tool	Install	Use Case	Set as Default
Antigravity CLI	Install from antigravity.google	Terminal agent paired with the Antigravity IDE	`git gtr config set gtr.ai.default antigravity`
Aider	`python -m pip install aider-install && aider-install`	Pair programming and file editing	`git gtr config set gtr.ai.default aider`
Auggie CLI	`npm install -g @augmentcode/auggie`	Context-aware agentic CLI for automation and development	`git gtr config set gtr.ai.default auggie`
Claude Code	Install from claude.com	Terminal-native coding agent	`git gtr config set gtr.ai.default claude`
Codex CLI	`npm install -g @openai/codex`	OpenAI coding agent	`git gtr config set gtr.ai.default codex`
GitHub Copilot CLI	`npm install -g @github/copilot` or `brew install copilot-cli`	GitHub's terminal coding agent	`git gtr config set gtr.ai.default copilot`
Cursor Agent	Install the `agent` CLI from cursor.com	Cursor's standalone terminal agent	`git gtr config set gtr.ai.default cursor`
Gemini CLI	`npm install -g @google/gemini-cli`	Open-source coding agent powered by Gemini	`git gtr config set gtr.ai.default gemini`
OpenCode	Install from opencode.ai	Open-source terminal coding agent	`git gtr config set gtr.ai.default opencode`
Continue (legacy)	Existing `cn` installations only	Compatibility; the project is no longer maintained	`git gtr config set gtr.ai.default continue`

Any safe executable command in PATH also works without a built-in adapter. For example, after installing Goose or Qwen Code:

git gtr config set gtr.ai.default goose
git gtr config set gtr.ai.default qwen

Examples:

# 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

# Then just use git gtr ai
git gtr ai my-feature

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

File Copying

Copy files to new worktrees using glob patterns:

# Add patterns to copy (multi-valued)
git gtr config add gtr.copy.include "**/.env.example"
git gtr config add gtr.copy.include "**/CLAUDE.md"
git gtr config add gtr.copy.include "*.config.js"

# Exclude patterns (multi-valued)
git gtr config add gtr.copy.exclude "**/.env"
git gtr config add gtr.copy.exclude "**/secrets.*"

Using .worktreeinclude file

Alternatively, create a .worktreeinclude file in your repository root:

# .worktreeinclude - files to copy to new worktrees
# Comments start with #

**/.env.example
**/CLAUDE.md
*.config.js

The file uses .gitignore-style syntax (one pattern per line, # for comments, empty lines ignored). Patterns from .worktreeinclude are merged with gtr.copy.include config settings - both sources are used together.

Security Best Practices

The key distinction: Development secrets (test API keys, local DB passwords) are low risk on personal machines. Production credentials are high risk everywhere.

# Personal dev: copy what you need to run dev servers
git gtr config add gtr.copy.include "**/.env.development"
git gtr config add gtr.copy.include "**/.env.local"
git gtr config add gtr.copy.exclude "**/.env.production"  # Never copy production

Tip

The tool only prevents path traversal (../). Everything else is your choice - copy what you need for your worktrees to function.

Directory Copying

Copy entire directories (like node_modules, .venv, vendor) to avoid reinstalling dependencies:

# Copy dependency directories to speed up worktree creation
git gtr config add gtr.copy.includeDirs "node_modules"
git gtr config add gtr.copy.includeDirs ".venv"
git gtr config add gtr.copy.includeDirs "vendor"
git gtr config add gtr.copy.includeDirs "packages/*/generated"

Directory include patterns are relative to the repository root. Literal paths are checked directly, * and ? match within the pattern's explicit depth, and ** enables recursive matching when a full-tree search is intentional. For backward compatibility, a bare basename that has no root-level match falls back to a recursive search. Prefer an explicit nested path to avoid that scan.

# Exclude specific nested directories (supports glob patterns)
git gtr config add gtr.copy.excludeDirs "node_modules/.cache"  # Exclude exact path
git gtr config add gtr.copy.excludeDirs "node_modules/.npm"    # Exclude npm cache (may contain tokens)

# Exclude using wildcards
git gtr config add gtr.copy.excludeDirs "node_modules/.*"      # Exclude all hidden dirs in node_modules
git gtr config add gtr.copy.excludeDirs "*/.cache"             # Exclude .cache at any level

Warning

Dependency directories may contain sensitive files (credentials, tokens, cached secrets). Always use gtr.copy.excludeDirs to exclude sensitive subdirectories if needed.

Use cases:

JavaScript/TypeScript: Copy node_modules to avoid npm install (can take minutes for large projects)
Python: Copy .venv or venv to skip pip install
PHP: Copy vendor to skip composer install
Go: Copy build caches in .cache or bin directories

How it works: The tool uses find to locate directories by name and copies them with cp -r. This is much faster than reinstalling dependencies but uses more disk space.

Hooks

Run custom commands during worktree operations:

# 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, gtr new --cd, or gtr pr --cd, in current shell)
git gtr config add gtr.hook.postCd "source ./vars.sh"

Hook execution order:

Hook	Timing	Use Case
`postCreate`	After worktree creation	Setup, install dependencies
`preRemove`	Before worktree deletion	Cleanup requiring directory access
`postRemove`	After worktree deletion	Notifications, logging
`postCd`	After `gtr cd`, `gtr new --cd`, or `gtr pr --cd` changes directory	Re-source environment, update shell context

Note: Pre-remove hooks abort removal on failure. Use --force to skip failed hooks.

Note: postCd hooks run in the current shell (not a subshell) so they can modify environment variables. They only run via shell integration (gtr cd, gtr new --cd, gtr pr --cd), not raw git gtr commands or git gtr go. Failures warn but don't undo the directory change.

Environment variables available in hooks:

REPO_ROOT - Repository root path
WORKTREE_PATH - Worktree path
BRANCH - Branch name

Examples for different build tools:

# Node.js (npm)
git gtr config add gtr.hook.postCreate "npm install"

# Node.js (pnpm)
git gtr config add gtr.hook.postCreate "pnpm install"

# Python
git gtr config add gtr.hook.postCreate "pip install -r requirements.txt"

# Ruby
git gtr config add gtr.hook.postCreate "bundle install"

# Rust
git gtr config add gtr.hook.postCreate "cargo build"

UI Settings

Control color output behavior.

Git Config Key	`.gtrconfig` Key	Description	Values
`gtr.ui.color`	`ui.color`	Color output mode	`auto` (default), `always`, `never`

# Disable color output
git gtr config set gtr.ui.color never

# Force color output (e.g., when piping to a pager)
git gtr config set gtr.ui.color always

Precedence: NO_COLOR env (highest) > GTR_COLOR env > gtr.ui.color config > auto-detect (TTY).

The NO_COLOR environment variable (no-color.org) always wins regardless of other settings.

Shell Completions

Enable tab completion using the built-in completion command. Homebrew installs native Bash, Zsh, and Fish completion files automatically, so manual setup is mainly for source installs or explicit shell configuration.

Bash

Requires bash-completion v2:

# macOS
brew install bash-completion@2

# Ubuntu/Debian
sudo apt install bash-completion

# Add to ~/.bashrc
source <(git gtr completion bash)

Zsh

Add to ~/.zshrc before any existing compinit call:

eval "$(git gtr completion zsh)"

Why before compinit?

Zsh needs to know gtr is a valid git subcommand before the completion system initializes. The completion zsh command outputs the required zstyle registration.

Fish

mkdir -p ~/.config/fish/completions
git gtr completion fish > ~/.config/fish/completions/git-gtr.fish

Configuration Examples

Minimal Setup (Just Basics)

git gtr config set gtr.worktrees.prefix "wt-"
git gtr config set gtr.defaultBranch "main"

Full-Featured Setup (Node.js Project)

# Worktree settings
git gtr config set gtr.worktrees.prefix "wt-"

# Editor
git gtr config set gtr.editor.default cursor

# Copy environment templates
git gtr config add gtr.copy.include "**/.env.example"
git gtr config add gtr.copy.include "**/.env.development"
git gtr config add gtr.copy.exclude "**/.env.local"

# Build hooks
git gtr config add gtr.hook.postCreate "pnpm install"
git gtr config add gtr.hook.postCreate "pnpm run build"

Global Defaults

# Set global preferences
git gtr config set gtr.editor.default cursor --global
git gtr config set gtr.ai.default claude --global
git gtr config set gtr.defaultRemote upstream --global

Environment Variables

For the variables that back a gtr.* key (GTR_WORKTREES_DIR, GTR_WORKTREES_PREFIX, GTR_DEFAULT_BRANCH, GTR_DEFAULT_REMOTE, GTR_EDITOR_DEFAULT, GTR_AI_DEFAULT, GTR_PROVIDER), the environment value is used only when no git config or .gtrconfig source sets that key. The other variables are read directly and are not part of that order: GTR_DIR is resolved before any configuration loads, GTR_EDITOR_CMD and GTR_AI_CMD are consumed by the adapter loader, GTR_COLOR sets the initial color mode but a gtr.ui.color value of always or never replaces it, and NO_COLOR disables color regardless of any other setting.

Variable	Description	Default
`GTR_DIR`	Override script directory location	Auto-detected
`GTR_WORKTREES_DIR`	Override base worktrees directory	`gtr.worktrees.dir` config
`GTR_WORKTREES_PREFIX`	Folder name prefix for new worktrees	`gtr.worktrees.prefix` config
`GTR_DEFAULT_BRANCH`	Base branch for new worktrees	`gtr.defaultBranch` config (auto-detect)
`GTR_EDITOR_DEFAULT`	Default editor adapter	`gtr.editor.default` config
`GTR_AI_DEFAULT`	Default AI tool adapter	`gtr.ai.default` config
`GTR_EDITOR_CMD`	Custom editor command (e.g., `emacs`)	None
`GTR_EDITOR_CMD_NAME`	First word of `GTR_EDITOR_CMD` for availability checks	None
`GTR_AI_CMD`	Custom AI tool command (e.g., `copilot`)	None
`GTR_AI_CMD_NAME`	First word of `GTR_AI_CMD` for availability checks	None
`GTR_DEFAULT_REMOTE`	Remote used for default base refs and tracking	`origin`
`GTR_COLOR`	Override color output (`always`, `never`, `auto`)	`auto`
`GTR_PROVIDER`	Override hosting provider (`github` or `gitlab`)	Auto-detected from URL
`NO_COLOR`	Disable color output when set (no-color.org)	Unset

Hook environment variables (available in hook scripts):

Variable	Description
`REPO_ROOT`	Repository root path
`WORKTREE_PATH`	Worktree path
`BRANCH`	Branch name

Back to README | Advanced Usage | Troubleshooting