git-worktree-runner completions.instructions.md

Completions Instructions

Overview

Shell completions provide tab-completion for git gtr commands, flags, branches, and adapter names across Bash, Zsh, and Fish shells.

When to Update Completions

Always update all three completion files when:

• Adding new commands (e.g., git gtr new-command)
• Adding new flags to existing commands (e.g., --new-flag)
• Adding editor or AI adapters (completion must list available adapters)
• Changing command names or flag names

File Responsibilities

• completions/gtr.bash - Bash completion (requires bash-completion v2+)
• completions/_git-gtr - Zsh completion (uses Zsh completion system)
• completions/gtr.fish - Fish shell completion

Implementation Pattern

Each completion file implements:

1. Command completion - Top-level commands (new, rm, editor, ai, list, etc.)
2. Flag completion - Command-specific flags (e.g., --from, --force, --editor)
3. Branch completion - Dynamic completion of git branches plus special ID 1 (via git branch)
4. Adapter completion - Editor names (cursor, vscode, zed) and AI tool names (aider, claude, codex)

Testing Completions

Manual testing (no automated tests):

# Bash - source the completion file (requires git's bash completion to be loaded)
source completions/gtr.bash
git gtr <TAB>                    # Should show commands
git gtr new <TAB>                # Should show flags
git gtr go <TAB>                 # Should show branches + '1'
git gtr editor <TAB>             # Should show branches + '1'
git gtr editor --editor <TAB>    # Should show editor names

# Zsh - copy to fpath directory and reload (requires git's zsh completion)
mkdir -p ~/.zsh/completions
cp completions/_git-gtr ~/.zsh/completions/
# Add to ~/.zshrc: fpath=(~/.zsh/completions $fpath)
# Add to ~/.zshrc: autoload -Uz compinit && compinit
exec zsh  # Reload shell
git gtr <TAB>                    # Should show commands
git gtr new <TAB>                # Should show flags
git gtr go <TAB>                 # Should show branches + '1'

# Fish - symlink to ~/.config/fish/completions/
ln -s "$(pwd)/completions/gtr.fish" ~/.config/fish/completions/
exec fish  # Reload shell
git gtr <TAB>                    # Should show commands
git gtr new <TAB>                # Should show flags
git gtr go <TAB>                 # Should show branches + '1'