### Troubleshoot Missing Adapter (Install Tool)

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/04-adapters-reference.md

If an adapter is missing, ensure the corresponding tool is installed. This example shows installing 'cursor' via Homebrew and then re-checking adapter status.

```bash
# Install tool first, then gtr will auto-detect
brew install cursor
git gtr adapter  # Now shows [ready]
```

--------------------------------

### Minimal Setup

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/docs/configuration.md

Configure basic worktree prefix and default branch. Use this for a quick start.

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

--------------------------------

### Adapter Registry Example Explanation

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/04-adapters-reference.md

An example registry entry like `cursor|cursor|Cursor not found; install at https://cursor.com` specifies the configuration name, the command to execute, and a user-friendly error message.

```bash
cursor|cursor|Cursor not found; install at https://cursor.com
```

--------------------------------

### Configure Ruby Post-Create Hook

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/docs/configuration.md

Example of adding a bundle install command to the post-create hook for Ruby projects.

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

--------------------------------

### Install git-gtr with Script Installer

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/README.md

Clone the repository and run the install script for macOS or Linux.

```bash
git clone https://github.com/coderabbitai/git-worktree-runner.git
cd git-worktree-runner
./install.sh
```

--------------------------------

### Configure Node.js Post-Create Hook (npm)

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/docs/configuration.md

Example of adding an npm install command to the post-create hook for Node.js projects.

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

--------------------------------

### Example .gtrconfig File

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/03-configuration-reference.md

This example demonstrates the structure and common settings for a .gtrconfig file, including copy rules, hooks, defaults, UI preferences, and worktree directory/prefix configurations.

```gitconfig
[copy]
    include = **/.env.example
    include = .github/*.json
    include = *.config.js
    exclude = .env
    exclude = .env.*.local
    includeDirs = node_modules
    excludeDirs = node_modules/.cache

[hooks]
    postCreate = npm install
    postCreate = npm run build
    preRemove = npm test
    postCd = source ./vars.sh

[defaults]
    editor = cursor
    ai = claude
    remote = origin
    branch = main

[ui]
    color = auto

[worktrees]
    dir = .worktrees
    prefix = wt-

```

--------------------------------

### Configure Python Post-Create Hook

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/docs/configuration.md

Example of adding a pip install command to the post-create hook for Python projects.

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

--------------------------------

### Configure Node.js Post-Create Hook (pnpm)

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/docs/configuration.md

Example of adding a pnpm install command to the post-create hook for Node.js projects using pnpm.

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

--------------------------------

### Full-Featured Setup for Node.js

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/docs/configuration.md

Configure worktree settings, default editor, environment file copying, and build hooks for a Node.js project. This setup is comprehensive for development workflows.

```bash
# 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"
```

--------------------------------

### Minimal Git Worktree Runner Setup

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/03-configuration-reference.md

Configure the default editor and AI for basic usage.

```bash
git gtr config set gtr.editor.default cursor
git gtr config set gtr.ai.default claude
```

--------------------------------

### Claude AI Adapter Usage

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/04-adapters-reference.md

Demonstrates how to start the Claude AI tool for a feature, with examples for passing custom arguments or flags to the underlying 'claude' command. Use '--' to separate git-worktree-runner arguments from AI tool arguments.

```bash
# Start with default settings
git gtr ai my-feature
```

```bash
# Pass arguments to Claude
git gtr ai my-feature -- --model gpt-4
```

```bash
git gtr ai my-feature -- --continue
```

--------------------------------

### Hook Lifecycle Examples

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/05-advanced-features.md

Illustrates the sequence of events during worktree creation and removal, including when various hooks are executed.

```bash
git gtr new my-feature
├── Create worktree (git worktree add)
├── Copy files (copy_patterns, copy_directories)
├── Copy configs from .gtrconfig
└── Run postCreate hooks
    ├── npm install
    ├── npm run build
    └── Custom scripts

git gtr rm my-feature
└── Run preRemove hooks (abort removal on failure unless --force)
    ├── npm test
    └── Custom cleanup
└── Remove worktree (git worktree remove)
└── Run postRemove hooks (informational only)
    └── Cleanup scripts
```

--------------------------------

### Nano Editor Implementation

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/04-adapters-reference.md

Defines how to check if nano can be used and how to open a worktree with it. Ensure nano is installed and in your PATH.

```bash
editor_can_open() {
  command -v nano >/dev/null
}

editor_open() {
  local worktree_path="$1"
  nano -w "$worktree_path"
}
```

--------------------------------

### Start AI Tool in Worktree

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/README.md

Start the configured AI tool for a specific worktree.

```bash
git gtr ai my-feature           # Start claude
```

--------------------------------

### Configuration Merging Example

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/05-advanced-features.md

Illustrates how multi-valued configuration keys like copy include patterns are merged and deduplicated across global, repository-local, and .gtrconfig scopes.

```bash
# .gtrconfig
# [copy]
#     include = **/.env.example
#     include = *.config.js

# Result when querying gtr.copy.include:
# **/.env.example  (deduplicated)
# .github/*.json
# *.config.js
```

--------------------------------

### Check Git Worktree Runner Setup

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/docs/troubleshooting.md

Run this command to diagnose potential setup issues with the git-worktree-runner. It performs a series of checks to ensure your environment is configured correctly.

```bash
git gtr doctor
```

--------------------------------

### Available Shell Commands

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/03-configuration-reference.md

Examples of using git-worktree-runner commands after shell integration is set up.

```bash
gtr cd                    # Interactive worktree picker (requires fzf)
gtr cd my-feature         # Navigate to specific worktree
gtr cd 1                  # Navigate to main repo
gtr new feature --cd      # Create and cd (requires shell integration)
```

--------------------------------

### Add AI Tool Adapter via Registry

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/CONTRIBUTING.md

Example of how to register a new AI tool adapter by adding a line to the `_AI_REGISTRY` in `lib/adapters.sh`.

```bash
yourname|yourcmd|YourTool not found. Install with: ...|Extra info line 1;Extra info line 2
```

--------------------------------

### Install git-gtr with Homebrew

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/README.md

Use Homebrew to tap the coderabbitai/tap and install the git-gtr package on macOS.

```bash
brew tap coderabbitai/tap
brew install git-gtr
```

--------------------------------

### Add Editor Adapter via Registry

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/CONTRIBUTING.md

Example of how to register a new editor adapter by adding a line to the `_EDITOR_REGISTRY` in `lib/adapters.sh`.

```bash
yourname|yourcmd|standard|YourEditor not found. Install from https://...|flags
```

--------------------------------

### Install Fish Shell Completion

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/README.md

Manually install Fish shell completions by creating the necessary directory and redirecting the output of the git gtr completion fish command to the completions file.

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

--------------------------------

### Fish Shell Integration Setup

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/03-configuration-reference.md

Add this to your ~/.config/fish/config.fish to enable git-worktree-runner shell commands.

```fish
set -l _gtr_init (test -n "$XDG_CACHE_HOME" && echo $XDG_CACHE_HOME || echo $HOME/.cache)/gtr/init-gtr.fish
test -f "$_gtr_init"; or git gtr init fish >/dev/null 2>&1
source "$_gtr_init" 2>/dev/null
```

--------------------------------

### Bash Script Best Practices Example

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/CONTRIBUTING.md

Illustrates recommended Bash scripting practices including strict mode, variable quoting, and error handling.

```bash
#!/usr/bin/env bash
# Brief description of what this file does

# Function description
do_something() {
  local input="$1"
  local result

  if [ -z "$input" ]; then
    log_error "Input required"
    return 1
  fi

  result=$(some_command "$input")
  printf "%s" "$result"
}
```

--------------------------------

### Check git-gtr Installation

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/docs/troubleshooting.md

Verify that the git-gtr command is installed and accessible in your PATH. If not found, re-run the installation script.

```bash
# Check if symlink exists (if neither exists, re-run ./install.sh)
ls -la /usr/local/bin/git-gtr 2>/dev/null || ls -la ~/bin/git-gtr 2>/dev/null

# Check if git-gtr is findable
which git-gtr

# Check your PATH includes the install location
echo $PATH | tr ':' '
' | grep -E "(local/bin|/bin$)"
```

--------------------------------

### Get Help Information

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/01-command-reference.md

Access help documentation for gtr commands. You can get overall help or specific help for a particular command by appending the command name.

```bash
git gtr help
```

```bash
git gtr help new
```

```bash
git gtr new --help
```

```bash
git gtr new -h
```

--------------------------------

### Example Commit: New Feature

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/CONTRIBUTING.md

An example of a commit message for a new feature, including a type, short description, longer description, and a footer referencing an issue.

```markdown
feat: add JetBrains IDE adapter

Add support for opening worktrees in IntelliJ, PyCharm, and other
JetBrains IDEs via the 'idea' command.

Closes #42
```

--------------------------------

### Manual Installation: User-local Link

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/README.md

Create a symbolic link for the git-gtr executable in ~/.local/bin for user-local access without sudo. Ensure ~/.local/bin is in your PATH or add it to your shell configuration.

```bash
mkdir -p ~/.local/bin
ln -s "$(pwd)/bin/git-gtr" ~/.local/bin/git-gtr
# Add to ~/.zshrc or ~/.bashrc if ~/.local/bin is not in PATH:
# export PATH="$HOME/.local/bin:$PATH"
```

--------------------------------

### Manual Installation: System-wide Link

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/README.md

Create a symbolic link for the git-gtr executable in /usr/local/bin for system-wide access on macOS (Intel) or Linux. Requires sudo privileges.

```bash
sudo mkdir -p /usr/local/bin
sudo ln -s "$(pwd)/bin/git-gtr" /usr/local/bin/git-gtr
```

--------------------------------

### Setup Disposable Repository for Testing

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/CLAUDE.md

Initialize a temporary Git repository for isolated testing of git-worktree-runner. This prevents interference with your main working tree.

```bash
mkdir -p /tmp/gtr-test && cd /tmp/gtr-test && git init && git commit --allow-empty -m "init"
```

```bash
/path/to/git-worktree-runner/bin/gtr new test-feature
```

--------------------------------

### Start AI Tool in Worktree (Bash)

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/04-adapters-reference.md

Starts the 'claude' AI tool within the specified worktree directory. The function changes the directory to the worktree and then executes 'claude' with any additional provided arguments. It's important that 'cd' into the worktree happens before starting the tool.

```bash
ai_start() {
  local worktree_path="$1"
  shift
  cd "$worktree_path" && claude "$@"
}
```

--------------------------------

### Configure Custom Workflow Scripts

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/docs/advanced-usage.md

Define project-specific git gtr configurations and setup hooks by creating a `.gtr-setup.sh` file in your repository.

```bash
#!/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"
```

--------------------------------

### Zsh Shell Integration Setup

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/03-configuration-reference.md

Add this to your ~/.zshrc to enable git-worktree-runner shell commands.

```bash
_gtr_init="${XDG_CACHE_HOME:-$HOME/.cache}/gtr/init-gtr.zsh"
[[ -f "$_gtr_init" ]] || eval "$(git gtr init zsh)" || true
source "$_gtr_init" 2>/dev/null || true; unset _gtr_init
```

--------------------------------

### List Available Adapters

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/01-command-reference.md

Use this command to see which editor and AI tool adapters are available and their current status. It helps in identifying missing tools that might need installation or PATH configuration.

```bash
git gtr adapter
```

```bash
git gtr adapters
```

```bash
$ git gtr adapter
Available Adapters

Editors:
NAME             STATUS          NOTES
cursor           [ready]         
vscode           [ready]         
nano             [missing]       Not found in PATH

AI Tools:
claude           [ready]         
eider            [missing]       Not found in PATH
```

--------------------------------

### Install Bash Shell Completion

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/README.md

Manually install Bash shell completions by sourcing the output of the git gtr completion bash command into your ~/.bashrc file.

```bash
# Bash (~/.bashrc)
source <(git gtr completion bash)
```

--------------------------------

### Configure Rust Post-Create Hook

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/docs/configuration.md

Example of adding a cargo build command to the post-create hook for Rust projects.

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

--------------------------------

### Multi-Repository Setup with Git Worktree Runner

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/03-configuration-reference.md

Configure global defaults that apply to all repositories and override them with local settings for specific projects.

```bash
# Global defaults apply to all repos
git gtr config set gtr.editor.default cursor --global
git gtr config set gtr.ai.default claude --global

# Override per-repo
cd /path/to/project-a
git gtr config set gtr.editor.default nano  # local only
```

--------------------------------

### Install Zsh Shell Completion

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/README.md

Manually install Zsh shell completions by evaluating the output of the git gtr completion zsh command in your ~/.zshrc file. Ensure this is placed before compinit.

```zsh
# Zsh (~/.zshrc) - must be before compinit
eval "$(git gtr completion zsh)"
```

--------------------------------

### Shell Function Signature Examples

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/README.txt

Illustrates how function signatures are represented, including required parameters, optional parameters, and variable arguments.

```shell
log_info "message"           # Required string param
```

```shell
cfg_get key [scope]          # Optional string param
```

```shell
parse_args spec "$@"         # Variable arguments
```

```shell
_ctx_repo_root               # Global variable
```

--------------------------------

### Full Development Setup for Git Worktree Runner

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/03-configuration-reference.md

Set up local, global, and team-specific configurations for a comprehensive development environment. This includes editor, AI, worktree directory, UI color, file inclusions, and post-create hooks.

```bash
# Local (repo-specific)
git gtr config set gtr.editor.default cursor
git gtr config set gtr.ai.default claude

# Global (user-wide)
git gtr config set gtr.worktrees.dir ~/.worktrees --global
git gtr config set gtr.ui.color auto --global

# Team (.gtrconfig file)
git gtr config add gtr.copy.include "**/.env.example"
git gtr config add gtr.hook.postCreate "npm install"
```

--------------------------------

### Bash Shell Integration Setup

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/03-configuration-reference.md

Add this to your ~/.bashrc to enable git-worktree-runner shell commands.

```bash
_gtr_init="${XDG_CACHE_HOME:-$HOME/.cache}/gtr/init-gtr.bash"
[[ -f "$_gtr_init" ]] || eval "$(git gtr init bash)" || true
source "$_gtr_init" 2>/dev/null || true; unset _gtr_init
```

--------------------------------

### Interactive Picker Keybindings

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/03-configuration-reference.md

Keybindings available in the interactive worktree picker when fzf is installed.

```bash
- ctrl-e: open in editor
- ctrl-a: start AI tool
- ctrl-d: delete worktree
- ctrl-y: copy path to clipboard
- ctrl-r: refresh list
```

--------------------------------

### Navigate to Worktree (Alternative)

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/README.md

An alternative method to navigate to a worktree without relying on shell integration, by getting the worktree path.

```bash
cd "$(git gtr go my-feature)"   # Alternative without shell integration
```

--------------------------------

### Provider Detection Example

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/05-advanced-features.md

Demonstrates how git-worktree-runner auto-detects the hosting provider (GitHub or GitLab) from the origin remote URL for commands like `git gtr clean --merged`.

```bash
# GitHub
origin: https://github.com/user/repo.git → Uses 'gh' CLI

# GitLab
origin: https://gitlab.com/user/repo.git → Uses 'glab' CLI

# Self-hosted
origin: https://git.company.com/user/repo.git → Manual override needed:
git gtr config set gtr.provider gitlab
```

--------------------------------

### Create a New Worktree

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/README.md

Create a new worktree folder for a feature. Use the --editor flag to open in the configured editor or --ai to start the AI tool.

```bash
git gtr new my-feature          # Create worktree folder: my-feature
git gtr new my-feature --editor # Create and open in editor
git gtr new my-feature --ai     # Create and start AI tool
git gtr new my-feature -e -a    # Create, open editor, then start AI
```

--------------------------------

### Claude AI Adapter Implementation

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/04-adapters-reference.md

Defines functions to check if Claude is available and to start the Claude AI tool within a worktree. Ensure the 'claude' command is in your PATH.

```bash
ai_can_start() {
  command -v claude >/dev/null
}

ai_start() {
  local worktree_path="$1"
  shift
  cd "$worktree_path" && claude "$@"
}
```

--------------------------------

### Cursor AI Adapter Implementation

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/04-adapters-reference.md

Provides the implementation for the Cursor editor AI adapter, checking for the 'cursor' command and starting it within the specified worktree. Ensure 'cursor' is accessible in your system's PATH.

```bash
ai_can_start() {
  command -v cursor >/dev/null
}

ai_start() {
  local worktree_path="$1"
  shift
  cd "$worktree_path" && cursor "$@"
}
```

--------------------------------

### Team Configuration (.gtrconfig) Example

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/docs/configuration.md

Use a .gtrconfig file in your repository root to share settings across your team. This file supports sections for copy rules, directory copying, hooks, and default settings.

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

--------------------------------

### lib/config.sh - Configuration Management Functions

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/06-module-structure.md

Manages Git configuration and .gtrconfig file settings, providing functions to get, set, and manipulate configuration values.

```APIDOC
## cfg_get

### Description
Retrieves a single configuration value.

### Signature
`cfg_get <key> [<scope>]`

### Parameters
- **key** (string): The configuration key to retrieve.
- **scope** (string, optional): The scope for the configuration value (e.g., 'local', 'global').

### Returns
string: The configuration value.
```

```APIDOC
## cfg_get_all

### Description
Retrieves all values for a multi-valued configuration key, ensuring deduplication.

### Signature
`cfg_get_all <key> [<file_key>] [<scope>]`

### Parameters
- **key** (string): The configuration key.
- **file_key** (string, optional): A key to map to the .gtrconfig file.
- **scope** (string, optional): The scope for the configuration value.

### Returns
string: A deduplicated string of configuration values.
```

```APIDOC
## cfg_get_file

### Description
Retrieves a configuration value specifically from the .gtrconfig file.

### Signature
`cfg_get_file <key>`

### Parameters
- **key** (string): The configuration key to retrieve from .gtrconfig.

### Returns
string: The configuration value from .gtrconfig.
```

```APIDOC
## cfg_get_all_file

### Description
Retrieves all values for a multi-valued configuration key specifically from the .gtrconfig file.

### Signature
`cfg_get_all_file <key>`

### Parameters
- **key** (string): The configuration key to retrieve all values for from .gtrconfig.

### Returns
string: A string of all configuration values from .gtrconfig.
```

```APIDOC
## cfg_default

### Description
Retrieves a configuration value with support for environment variables and fallback values.

### Signature
`cfg_default <key> [<env_var>] [<fallback>]`

### Parameters
- **key** (string): The configuration key.
- **env_var** (string, optional): An environment variable to check for the value.
- **fallback** (string, optional): A fallback value if the key and environment variable are not set.

### Returns
string: The resolved configuration value.
```

```APIDOC
## cfg_bool

### Description
Retrieves a boolean configuration value, returning 0 for false and 1 for true.

### Signature
`cfg_bool <key> [<default>]`

### Parameters
- **key** (string): The configuration key.
- **default** (0/1, optional): The default value if the key is not found.

### Returns
0/1: The boolean configuration value.
```

```APIDOC
## cfg_map_to_file_key

### Description
Maps a Git configuration key (e.g., `gtr.*`) to its equivalent key in the .gtrconfig file.

### Signature
`cfg_map_to_file_key <gtr_key>`

### Parameters
- **gtr_key** (string): The Git configuration key.

### Returns
string: The corresponding .gtrconfig key.
```

```APIDOC
## cfg_map_from_file_key

### Description
Performs the reverse mapping: maps a .gtrconfig key to its equivalent Git configuration key (e.g., `gtr.*`).

### Signature
`cfg_map_from_file_key <file_key>`

### Parameters
- **file_key** (string): The .gtrconfig key.

### Returns
string: The corresponding Git configuration key.
```

--------------------------------

### Navigate to Worktree Path

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/README.md

Use `git gtr go` to print the worktree path, which can be used with `cd` for shell navigation. `gtr cd` provides an interactive picker if `fzf` is installed.

```bash
cd "$(git gtr go my-feature)"    # Navigate by branch name
```

```bash
cd "$(git gtr go 1)"             # Navigate to main repo
```

--------------------------------

### List Git Worktree Records

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/02-core-api.md

Lists all registered git worktrees with structured output. Use this to get a comprehensive overview of your worktree setup.

```bash
records=$(list_worktree_records "$repo_root")
```

```bash
records=$(list_worktree_records "$repo_root")
echo "$records" | while IFS= read -r line;
  case "$line" in
    "path ")
      path=("${line#path }")
      echo "Worktree: $path"
      ;;
  esac
done
```

--------------------------------

### Add Post-Creation Hook

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/01-command-reference.md

Adds a command to be executed as a hook after a new worktree is created. This allows for automated setup tasks like dependency installation.

```bash
git gtr config add gtr.hook.postCreate "npm install"
```

--------------------------------

### Use Porcelain Output for Bulk Operations

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/05-advanced-features.md

For bulk operations like clean or list, use porcelain output for easier scripting. This example demonstrates parsing the output into worktree path, branch, and status.

```bash
git gtr list --porcelain | while IFS=$'\t' read -r path branch status;
do
  echo "Worktree: $branch at $path ($status)"
done
```

--------------------------------

### Worktree Resolution Strategy Examples

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/05-advanced-features.md

Demonstrates flexible worktree identification using exact branch names, sanitized paths, partial matches, and the current directory. The resolution strategy prioritizes the special ID '1', followed by the current branch, sanitized path matches, and a full worktree scan.

```bash
# All equivalent (if on branch "feature-auth"):
git gtr editor feature-auth         # Exact match
git gtr editor "feature/auth"       # Matches sanitized folder "feature-auth"
git gtr editor feature              # Partial match (first match wins)
cd feature-auth && git gtr editor .  # Current directory (inferred)
```

--------------------------------

### Configure Personal Dev File Copy Includes

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/docs/configuration.md

Add patterns for files needed for personal development environments. Avoid copying production credentials.

```bash
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"
```

--------------------------------

### Example Commit: Bug Fix

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/CONTRIBUTING.md

An example of a commit message for a bug fix, detailing the issue and the solution implemented.

```markdown
fix: handle spaces in worktree paths

Properly quote paths in all commands to support directories with spaces.
```

--------------------------------

### Navigate to Worktree (with Shell Integration)

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/README.md

Create a new worktree and change the directory into it using shell integration. Also includes interactive picker and direct navigation.

```bash
gtr new my-feature --cd         # Create and cd (requires shell integration)
gtr cd                          # Interactive picker (requires fzf + shell integration)
gtr cd my-feature               # Requires shell integration (see below)
```

--------------------------------

### gtr version

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/01-command-reference.md

Displays the installed version of the git worktree runner (gtr) tool.

```APIDOC
## gtr version

### Description
Show installed version.

### Method
```bash
git gtr version
git gtr --version
git gtr -v
```

### Return
Prints: `git gtr version X.Y.Z`
```

--------------------------------

### Typical Command Structure

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/06-module-structure.md

Illustrates the standard structure for command functions within the project. It includes argument parsing, requirement checks, repository context resolution, and argument processing.

```bash
cmd_new() {
  parse_args "<spec>" "$@"
  require_args 1 "Usage: ..."
  resolve_repo_context || exit 1
  
  # Process arguments and call lib functions
  # Return 0 on success, non-zero on failure
}
```

--------------------------------

### Show GTR Version

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/01-command-reference.md

Display the installed version of the git worktree runner (gtr).

```bash
git gtr version
```

```bash
git gtr --version
```

```bash
git gtr -v
```

--------------------------------

### Load AI Adapter

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/06-module-structure.md

Loads a specific AI tool adapter by name. This action defines the `ai_can_start` and `ai_start` functions.

```bash
load_ai_adapter <name>
```

--------------------------------

### Set Editor Configuration with Flags

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/04-adapters-reference.md

Override-backed adapters can accept command-line flags. The primary command name is stripped, and remaining tokens are passed as arguments to the tool.

```bash
git gtr config set gtr.editor.default "nano -w"
```

```bash
git gtr config set gtr.editor.default "code --wait"
```

```bash
git gtr config set gtr.ai.default "claude --continue"
```

--------------------------------

### Run Commands in Worktree

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/README.md

Execute arbitrary commands within a specified worktree. For example, run npm tests.

```bash
git gtr run my-feature npm test # Run tests
```

--------------------------------

### postCd Hook Configuration

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/05-advanced-features.md

Demonstrates how to configure the postCd hook to source environment files, allowing variables to persist after navigation.

```bash
# When you do: gtr cd my-feature
# postCd hooks can source environment files:
git gtr config add gtr.hook.postCd "source ./vars.sh"
git gtr config add gtr.hook.postCd "set -a; source .env; set +a"
```

--------------------------------

### List All Git Worktrees

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/README.md

Lists all available Git worktrees. Use the `--porcelain` flag for machine-readable output.

```bash
git gtr list [--porcelain]
```

--------------------------------

### current_branch()

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/02-core-api.md

Gets the current branch name of a specified worktree, providing normalized handling for detached HEAD states.

```APIDOC
## current_branch(worktree_path)

### Description
Get the current branch of a worktree with normalized detached HEAD handling.

### Parameters
#### Path Parameters
- **worktree_path** (string) - Required - Absolute path to worktree directory

### Returns
Branch name (stdout), "(detached)" if detached, empty on error
```

--------------------------------

### Get Bash Version

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/docs/troubleshooting.md

Retrieve your current Bash version. This is helpful for troubleshooting shell-related issues and ensuring compatibility.

```bash
bash --version
```

--------------------------------

### Configure Post-Create Hooks

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/docs/configuration.md

Add commands to run after a worktree is created. Multiple commands are supported and run in the order they are added.

```bash
# 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"
```

--------------------------------

### Create a Custom Editor Adapter Script

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/04-adapters-reference.md

Define a custom bash script for an editor adapter. Implement `editor_can_open` to check for the tool's availability and `editor_open` to launch the editor with the worktree path.

```bash
#!/usr/bin/env bash
# Custom adapter for MyTool

editor_can_open() {
  command -v mytool >/dev/null
}

editor_open() {
  local worktree_path="$1"
  shift
  mytool --workspace "$worktree_path" "$@"
}
```

--------------------------------

### Setting Default AI Tool

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/04-adapters-reference.md

Demonstrates how to set the default AI tool, override it for a single command, or use an environment variable for CI/automation. This provides flexibility in choosing the AI assistant.

```bash
# Set AI tool
git gtr config set gtr.ai.default claude
```

```bash
# Override for single command
git gtr ai my-feature --ai aider
```

```bash
# Use in CI/automation
GTR_AI=aider git gtr ai feature -- --model gpt-4
```

--------------------------------

### Get Git Version

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/docs/troubleshooting.md

Retrieve your current Git version. This information is often required when reporting issues or checking compatibility.

```bash
git --version
```

--------------------------------

### Manage Worktrees Across Multiple Repositories

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/docs/advanced-usage.md

Each repository has its own independent set of worktrees. Switch between repositories using `cd` and manage their respective worktrees.

```bash
# Frontend repo
cd ~/GitHub/frontend
git gtr list
# BRANCH          PATH
# main [main]     ~/GitHub/frontend
# auth-feature    ~/GitHub/frontend-worktrees/auth-feature
# nav-redesign    ~/GitHub/frontend-worktrees/nav-redesign

git gtr editor auth-feature      # Open frontend auth work
git gtr ai nav-redesign          # AI on frontend nav work

# Backend repo (separate worktrees)
cd ~/GitHub/backend
git gtr list
# BRANCH          PATH
# main [main]     ~/GitHub/backend
# api-auth        ~/GitHub/backend-worktrees/api-auth
# websockets      ~/GitHub/backend-worktrees/websockets

git gtr editor api-auth          # Open backend auth work
git gtr ai websockets            # AI on backend websockets

# Switch back to frontend
cd ~/GitHub/frontend
git gtr editor auth-feature      # Opens frontend auth
```

--------------------------------

### Add git-gtr to PATH

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/docs/troubleshooting.md

Manually add the git-gtr installation directory to your PATH environment variable by exporting it in your shell configuration file.

```bash
# Add to ~/.zshrc or ~/.bashrc:
export PATH="/usr/local/bin:$PATH"
# Or if using ~/bin:
export PATH="$HOME/bin:$PATH"
```

--------------------------------

### Get Specific Configuration Value

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/01-command-reference.md

Retrieves and prints the value of a specific configuration key. If the key is not found, it will print an empty string.

```bash
git gtr config get gtr.editor.default
```

--------------------------------

### Set Default Editor

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/04-adapters-reference.md

Demonstrates setting the default editor using configuration precedence, overriding for a single command, or using environment variables for automation.

```bash
# Set editor (uses config precedence)
git gtr config set gtr.editor.default cursor
```

```bash
# Override for single command
git gtr editor my-feature --editor vscode
```

```bash
# Use in CI/automation
GTR_EDITOR=nano git gtr editor feature
```

--------------------------------

### Run Automated Tests with BATS

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/CLAUDE.md

Execute all automated tests in the 'tests/' directory using BATS. Ensure BATS is installed and tests are set up.

```bash
bats tests/
```

--------------------------------

### Get Worktree Status

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/02-core-api.md

Retrieves the status of a specific git worktree. The status indicates if the worktree is ok, detached, locked, prunable, or missing.

```bash
status=$(worktree_status "$worktree_path")
```

--------------------------------

### Configure Directory Copy Include Patterns

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/docs/configuration.md

Add directory names to be copied into new worktrees. This helps avoid reinstalling dependencies.

```bash
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"
```

--------------------------------

### CI/Automation Setup for Git Worktree Runner

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/03-configuration-reference.md

Configure gtr for non-interactive CI environments, disabling color and hooks, and specifying a custom editor.

```bash
# Non-interactive, no color
NO_COLOR=1 GTR_WORKTREES_DIR=/tmp/wt git gtr new feature --yes --no-hooks

# With specific editor
GTR_EDITOR=nano git gtr editor feature
```

--------------------------------

### Create a New Worktree

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/00-index.md

Use this command to create a new git worktree for a specified branch. This is a common starting point for new features or tasks.

```bash
git gtr new feature-branch
```

--------------------------------

### gtr init

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/01-command-reference.md

Generates shell integration code for `gtr cd` navigation, enabling interactive branch picking and creation with automatic directory changes.

```APIDOC
## gtr init

### Description
Generate shell integration code for `gtr cd` navigation.

### Method
```bash
git gtr init <shell> [--as <name>]
```

### Parameters
#### Path Parameters
- **shell** (string) - Required - Shell type: bash, zsh, or fish
- **--as** (string) - Optional - Function name (if gtr conflicts with another tool)

### Return
Prints shell function code suitable for sourcing in shell rc files. Output is auto-cached to `~/.cache/gtr/`.

### Examples
```bash
# Generate for bash
git gtr init bash

# Generate for zsh
git gtr init zsh

# Use custom function name (avoid conflicts)
eval "$(git gtr init bash --as gwtr)"
gwtr cd my-feature
```

Resulting functions enable:
```bash
gtr cd [<branch>]      # Interactive picker (with fzf) or direct navigation
gtr new feature --cd   # Create and cd (requires shell integration)
```
```

--------------------------------

### Get Config Value with Fallback Support

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/02-core-api.md

Retrieves a configuration value, prioritizing git config, then an environment variable, and finally a hardcoded fallback value.

```bash
value=$(cfg_default "gtr.editor.default" "GTR_EDITOR" "vscode")
```

```bash
editor=$(cfg_default "gtr.editor.default" "GTR_EDITOR" "nano")
```

--------------------------------

### List Available Editor & AI Adapters

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/README.md

Displays a list of all available editor and AI adapters that can be used with the Git Worktree Runner.

```bash
git gtr adapter
```

--------------------------------

### Trust System - Execution After Trust

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/05-advanced-features.md

Demonstrates that commands are executed without error after the .gtrconfig has been trusted.

```bash
git gtr new feature
# Now runs postCreate hooks (already trusted)
```

--------------------------------

### Navigate Between Worktrees

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/docs/advanced-usage.md

Switch between worktrees for different branches or PRs. Use shell integration for direct navigation or `git gtr go` to get the path.

```bash
# 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
```

--------------------------------

### Safe Command Execution with 'set -e'

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/06-module-structure.md

Demonstrates how to safely execute commands that might return a non-zero exit code when 'set -e' is active. Always guard potentially failing commands with an 'if' statement or '|| true' to prevent unexpected script termination.

```bash
# DANGEROUS: if my_func returns 1, script exits
result=$(my_func)
```

```bash
# SAFE: guards the return with if
if result=$(my_func); then
  ...
fi
```

```bash
# SAFE: explicit || true
result=$(my_func) || true
```

--------------------------------

### Git Worktree Runner Health Check

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/README.md

Performs a health check on the Git Worktree Runner environment, verifying Git installation, editors, and AI tools.

```bash
git gtr doctor
```

--------------------------------

### Configure File Copy Include Patterns

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/docs/configuration.md

Add glob patterns for files to be copied into new worktrees. These settings are multi-valued.

```bash
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"
```

--------------------------------

### Check AI Tool Availability (Bash)

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/04-adapters-reference.md

Checks if the 'claude' command is available in the system's PATH. This function is used to determine if the AI tool can be started.

```bash
ai_can_start() {
  command -v claude >/dev/null
}
```

--------------------------------

### AI Functions after Loading Adapter

Source: https://github.com/coderabbitai/git-worktree-runner/blob/main/_autodocs/06-module-structure.md

These functions are defined after loading an AI adapter with `load_ai_adapter`. `ai_can_start` checks if the tool is available, returning 0 or 1.

```bash
ai_can_start()
```

```bash
ai_start()
```