Skip to content
This repository was archived by the owner on Nov 18, 2026. It is now read-only.

Latest commit

 

History

History
640 lines (463 loc) · 29.5 KB

configuration.md

File metadata and controls

640 lines (463 loc) · 29.5 KB

Configuration Reference

Complete configuration guide for git-worktree-runner

Back to README | Advanced Usage | Troubleshooting


Table of Contents


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):

  1. git config --local (.git/config) - personal overrides
  2. .gtrconfig (repo root) - team defaults
  3. git config --global (~/.gitconfig) - user defaults
  4. git config --system (/etc/gitconfig) - system defaults
  5. Environment variables
  6. 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.

Configuration safety

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/config

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


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.

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.


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 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 = upstream

The 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/" >> .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:

Workspace files:

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

  1. If gtr.editor.workspace is set to a path, opens that file (relative to and contained within the worktree root)
  2. If set to none, disables workspace lookup (always opens folder)
  3. Otherwise, auto-detects any *.code-workspace file in the worktree root
  4. 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.


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.*"

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.

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

File 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_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

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"

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