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
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 defaultsgit config --global(~/.gitconfig) - user defaultsgit config --system(/etc/gitconfig) - system defaults- Environment variables
- Default values
For the CLI, a bare repository's root is the bare Git directory itself, including
when a command is run from one of its linked worktrees. .gtrconfig,
.worktreeinclude, relative worktree locations, and the default copy source use
that root, never its parent directory. The default worktree location is a sibling
named <bare-directory-name>-worktrees. Files stored only in Git history are not
copy sources; use git gtr copy --from <worktree> to copy from a checkout.
Before using native Git configuration, GTR checks that configuration files and
their paths are owned by the current user or root and cannot be written or
replaced by other users. The check includes local, global, system, and linked
worktree configuration, included files, symlinks, and parent directories. It
rejects group/other write permissions and, on macOS, write-capable ACL grants.
Trusted-owner sticky directories such as /tmp are allowed when they protect
an existing entry owned by the current user or root. Unreadable permissions or
configuration fail closed.
An unsafe source stops the command before GTR creates a worktree, honors a
configured destination, or launches configured commands. Hook dispatch and
generated Bash/Zsh/Fish postCd helpers also check the destination worktree's
configuration. A .gtrconfig approval never overrides unsafe Git permissions.
The error names the path that needs attention. For example, if your own
.git/config is group-writable, remove group/other write access:
chmod go-w .git/configSecure any reported parent directories, included files, or ACLs as well; do not change ownership or permissions on files you do not manage. Shared repositories that deliberately grant other users write access need separate private clones for GTR use. After upgrading, reload the documented shell setup or restart your shell so cached integration is regenerated; already-loaded functions retain their old behavior until reloaded.
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 = upstreamTip
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.
Approval is bound to the repository path, the filesystem identities of its common Git directory and object database, and a commit recorded outside the repository in the approval marker. Replacing the object database requires new approval even if .git itself and shared history are retained. Current history must also share an ancestor with the approved commit; retaining old objects, replace refs, grafts, or a forged commit-graph cache does not establish shared history. This check uses local commit objects and never fetches missing history. Normal commits, garbage collection, related branches, and linked worktrees retain approval. Orphan histories and shallow or rewritten histories with no available common ancestor need new approval. Create an initial commit before approving commands.
This is command-definition trust: scripts, dependencies, and tools invoked by approved commands are not hashed or pinned, so their contents can change within the trusted repository. Rewriting files while deliberately retaining both directory instances and shared history is indistinguishable from an update to that repository. Review delegated code and trust its contributors before approving.
Command definitions are captured once for trust verification and consumption, with NUL-delimited records preserving multiline values. The version 4 trust format invalidates older approvals; review commands again with git gtr trust after upgrading.
Each directory's identity includes device, inode, and birth time with nanosecond precision. Both the common Git directory and the object database directory require a known birth time. If the filesystem or stat implementation cannot provide either one, approval fails closed and .gtrconfig executable commands remain disabled.
# 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 name prefix, without / or \ (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 = upstreamThe prefix is prepended literally to the sanitized folder name: dev- and
feature/auth produce dev-feature-auth. Empty prefixes are supported. Prefixes
containing / or \ are rejected from every configuration source, including
.gtrconfig and GTR_WORKTREES_PREFIX. Use gtr.worktrees.dir to select a parent
directory; for example, replace a team/dev- prefix with a dev- prefix and a
base directory ending in team.
Important
If storing worktrees inside the repository, add the directory to .gitignore.
echo "/.worktrees/" >> .gitignoreIf 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 = trueOn 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-sparseNote
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.
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 = gitlabSetup:
# Self-hosted GitLab
git gtr config set gtr.provider gitlab
# Self-hosted GitHub Enterprise
git gtr config set gtr.provider githubRequired CLI tools:
| Provider | CLI Tool | Install |
|---|---|---|
| GitHub | gh |
cli.github.com |
| GitLab | glab |
gitlab.com/gitlab-org/cli |
# 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-workspaceSetup editors:
- Antigravity: Install from antigravity.google, with the
agy-idecommand available - Cursor: Install from cursor.com, enable shell command
- VS Code: Install from code.visualstudio.com, enable
codecommand - Zed: Install from zed.dev,
zedcommand 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.workspaceis set to a path, opens that file (relative to and contained within the worktree root) - If set to
none, disables workspace lookup (always opens folder) - Otherwise, auto-detects any
*.code-workspacefile in the worktree root - Falls back to opening the folder if no valid workspace file is found
Workspace paths from every config source must resolve to a file inside the selected worktree. Nested paths, spaces, and symlinks that resolve inside the worktree are supported. Absolute configured paths and paths or symlinks that resolve outside the worktree are ignored. An invalid or missing explicit path opens the folder; it does not trigger auto-detection. Previously accepted outside-worktree paths now open the folder instead.
The shared .gtrconfig editor.workspace setting is workspace data and does not
require command approval. Selecting an editor through .gtrconfig
defaults.editor still requires git gtr trust; a local/global editor default
or an explicit --editor can also select the editor. Containment applies to the
workspace file itself, not the folders or settings described inside it. The
editor remains responsible for its own workspace trust checks.
# Default AI tool: none (or antigravity, aider, auggie, claude, codex, copilot, cursor, gemini, opencode)
gtr.ai.default = noneBuilt-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 qwenExamples:
# 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"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.*"File exclusions match source paths relative to the repository root. A leading
**/ matches zero or more directory levels: **/note.txt excludes note.txt,
data/note.txt, and deeper matches. A literal note.txt excludes only the root
path. Other shell wildcard behavior is preserved, including * matching /
in exclusions, so *.txt excludes matching files at any depth.
Alternatively, create a .worktreeinclude file in your repository root:
# .worktreeinclude - files to copy to new worktrees
# Comments start with #
**/.env.example
**/CLAUDE.md
*.config.jsThe 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.
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 productionTip
The tool only prevents path traversal (../). Everything else is your choice - copy what you need for your worktrees to function.
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.
Trailing slashes on directory include and exclude patterns are ignored:
vendor/ and vendor both copy to <worktree>/vendor and use the same exclusions.
# 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 levelFile exclusions in gtr.copy.exclude also apply inside directories selected by
gtr.copy.includeDirs, for both git gtr new and git gtr copy. They match
repository-relative file paths using the same rules as file-pattern copying.
For example, *.pem skips PEM files throughout an included directory. Files
are skipped before copying; existing excluded files in the destination are
left unchanged. File exclusions do not exclude directories with matching names;
use gtr.copy.excludeDirs to skip a whole directory.
When exclusions require selective copying, new destination directories stay owner-only until their contents are copied successfully. Missing ancestors of nested directory selections stay private until all selected directories finish. Their final permission bits come from the corresponding source directory, restricted by your umask. Existing destination directory permissions are left unchanged.
Directory exclusions never descend through symlinks. An exclusion matching a
symlink itself removes only the link, including when the pattern ends in /;
the link target is preserved. Exclusions are skipped when the copied directory
or one of its path components is a symlink.
If directory copying fails, git gtr new and git gtr pr stop before running
post-create hooks or automatically launching tools. The created worktree is
left in place for inspection and cleanup.
Keep copy sources, destination worktrees, and their parent directories writable only by trusted users. A user who can replace a worktree path or modify a copied tool can change what a hook executes. Hook approval covers command definitions; it does not pin the contents of delegated scripts or dependencies. Copy path checks cannot isolate execution from other users who can mutate those paths.
Warning
Dependency directories may contain sensitive files (credentials, tokens, cached secrets). Use gtr.copy.excludeDirs to exclude sensitive subdirectories and gtr.copy.exclude to exclude files.
Use cases:
- JavaScript/TypeScript: Copy
node_modulesto avoidnpm install(can take minutes for large projects) - Python: Copy
.venvorvenvto skippip install - PHP: Copy
vendorto skipcomposer install - Go: Copy build caches in
.cacheorbindirectories
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.
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
--forceto skip failed hooks.Note:
postCdhooks 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 rawgit gtrcommands orgit gtr go. Failures warn but don't undo the directory change.
Environment variables available in hooks:
REPO_ROOT- Repository root pathWORKTREE_PATH- Worktree pathBRANCH- Branch name
For rm hooks and ai postCd hooks, BRANCH is empty when the target has
detached HEAD. The (detached) label shown by list is display text, not a
branch identity. Shell integration's gtr cd hooks retain Git's HEAD label
for detached HEAD.
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"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 alwaysPrecedence: 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.
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.
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)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.
mkdir -p ~/.config/fish/completions
git gtr completion fish > ~/.config/fish/completions/git-gtr.fishgit gtr config set gtr.worktrees.prefix "wt-"
git gtr config set gtr.defaultBranch "main"# 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"# 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 --globalFor 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 |