Troubleshooting Guide

Solutions for common issues with git-worktree-runner

Back to README | Configuration | Advanced Usage

---

Table of Contents

• Installation Issues
• Worktree Creation Issues
• Editor Issues
• File Copying Issues
• Platform Support
• Architecture Overview
• Reliability & Testing Status

---

Installation Issues

"git: 'gtr' is not a git command"

This error means git-gtr is not in your PATH. Verify installation:

# 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 ':' '\n' | grep -E "(local/bin|/bin$)"

Fix: Re-run ./install.sh or manually add the symlink location to your PATH:

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

Then restart your terminal.

---

Worktree Creation Issues

Worktree Creation Fails

# Ensure you've fetched latest refs
git fetch origin

# Check if branch already exists
git branch -a | grep your-branch

# Manually specify tracking mode
git gtr new test --track remote

Branch Already Checked Out

If you get an error about a branch already being checked out, the branch exists in another worktree. Options:

1. Use a different branch name
2. Remove the existing worktree first: git gtr rm <branch>
3. Use --force --name <suffix> to create a second worktree on the same branch (advanced)

---

Editor Issues

Editor Not Opening

# Verify editor command is available
command -v cursor  # or: code, zed

# Check configuration
git gtr config get gtr.editor.default

# Try opening again
git gtr editor my-feature

Wrong Editor Opens

Check your configuration precedence:

# Check local config
git config --local gtr.editor.default

# Check global config
git config --global gtr.editor.default

# Check .gtrconfig file
cat .gtrconfig 2>/dev/null | grep editor

---

File Copying Issues

Files Not Being Copied

# Check your patterns
git gtr config get gtr.copy.include

# Test patterns with find
cd /path/to/repo
find . -path "**/.env.example"

# Check if patterns are being excluded
git gtr config get gtr.copy.exclude

Pattern Syntax Issues

• Use ** for recursive matching: **/.env.example
• Use * for single-level wildcard: *.config.js
• Patterns are relative to repository root

---

Platform Support

Platform	Status	Notes
macOS	Full support	Ventura+
Linux	Full support	Ubuntu, Fedora, Arch, etc.
Windows	Via Git Bash or WSL	Native PowerShell not supported

Platform-Specific Notes

macOS:

• GUI opening uses open
• Terminal spawning uses iTerm2/Terminal.app
• Bash 3.2 ships by default (works, but 4.0+ recommended)

Linux:

• GUI opening uses xdg-open
• Terminal spawning uses gnome-terminal/konsole
• Most distros have Bash 4.0+

Windows:

• GUI opening uses start
• Requires Git Bash or WSL
• PowerShell is not supported (use Git Bash instead)

---

Architecture Overview

git-worktree-runner/
├── bin/
│   ├── git-gtr         # Entry point: sources lib/*.sh, dispatches commands
│   └── gtr             # Development wrapper (exec bin/git-gtr)
├── lib/                 # Core libraries
│   ├── core.sh         # Git worktree operations
│   ├── config.sh       # Configuration management
│   ├── platform.sh     # OS-specific code
│   ├── ui.sh           # User interface
│   ├── copy.sh         # File copying
│   ├── hooks.sh        # Hook execution
│   ├── args.sh         # Argument parsing
│   ├── provider.sh     # GitHub/GitLab detection
│   ├── adapters.sh     # Editor & AI adapter registry
│   ├── launch.sh       # Editor & AI launching
│   └── commands/       # One file per subcommand
├── adapters/           # Editor & AI tool plugins
│   ├── editor/
│   └── ai/
├── completions/        # Shell completions
└── templates/          # Example configs

---

Reliability & Testing Status

Current Status: Production-ready for daily use

Tested Platforms

Platform	Versions
macOS	Ventura (13.x), Sonoma (14.x), Sequoia (15.x)
Linux	Ubuntu 22.04/24.04, Fedora 39+, Arch Linux
Windows	Git Bash (tested), WSL2 (tested), PowerShell (not supported)

Git Versions

Version	Support Level
Git 2.25+	Recommended
Git 2.22+	Full support
Git 2.17-2.21	Basic support (some features limited)
Git < 2.17	Not supported

Known Limitations

• Shell completions require bash-completion v2+ for Bash
• Some AI adapters require recent tool versions (see adapter docs)
• Native PowerShell is not supported; use Git Bash or WSL2

Testing Approach

• Automated tests: BATS test suite (tests/) covers core functions
• CI: ShellCheck linting + BATS tests run on all PRs
• Manual testing: End-to-end workflows tested across macOS, Linux, WSL2
• Adapter coverage: Built-in and generic PATH launch behavior is covered by BATS; product-specific behavior depends on installed tool versions
• Community testing appreciated - please report issues!

Experimental Features

Feature	Status
--force flag for same-branch worktrees	Use with caution
Windows PowerShell support	Not supported (use Git Bash or WSL)

---

Getting Help

If you're still having issues:

1. Run git gtr doctor to check your setup
2. Re-run with GTR_DEBUG=1 git gtr <command>; an unexpected failure prints ERROR at <file>:<line> in <function>(). Handled errors, such as a missing worktree, are reported normally and add no such line.
3. For a full trace, run the script directly: bash -x "$(command -v git-gtr)" <command>
4. Open an issue with:
   • Your OS and version
   • Git version (git --version)
   • Bash version (bash --version)
   • The command you ran
   • The error message

---

Back to README | Configuration | Advanced Usage