Enhance shell completion documentation and scripts for git gtr

- Updated README.md to clarify prerequisites for Bash and Zsh completions, including the need for git's completion system. - Improved completion instructions in completions.instructions.md to reflect changes in command structure and added details for testing completions. - Modified completion scripts for Bash, Zsh, and Fish to integrate better with their respective completion systems and added instructions for installation and usage.

Author: helizaga

.github/instructions/completions.instructions.md

@@ -27,40 +27,51 @@ Shell completions provide tab-completion for `git gtr` commands, flags, branches
 
 Each completion file implements:
 
-1.**Command completion** - Top-level commands (`new`, `rm`, `open`, `ai`, `list`, etc.)
+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 existing worktree branches (via `git gtr list --porcelain`)
+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
-# Bash - source the completion file
+# 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 open <TAB># Should show branches
-git gtr open --editor <TAB># Should show editor names
-
-# Zsh - fpath must include completions directory
-fpath=(completions $fpath)
-autoload -U compinit && compinit
-git gtr <TAB>
+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/_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/
-git gtr <TAB>
+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'
 ```
 
+**Important**: All shell completions require git's own completion system to be enabled for the `git` command. The completions integrate with git's subcommand completion framework.
+
 ## Branch Completion Logic
 
-All three completions dynamically fetch current worktree branches:
+All three completions dynamically fetch current git branches:
 
--Parse output of `git gtr list --porcelain` (tab-separated: `path\tbranch\tstatus`)
--Extract branch column (second field)
--Exclude the special ID `1`(main repo) if needed
+-Use `git branch --format='%(refname:short)'` to get branch names
+-Add special ID `1` for main repo (allows `git gtr go 1`, `git gtr editor 1`, etc.)
+-Return combined list of branches + `1`for commands that accept branch arguments (go, editor, ai, rm)
 
 ## Adapter Name Updates
 

README.md

@@ -123,7 +123,7 @@ source ~/.zshrc
 
 ### Shell Completions (Optional)
 
-**Bash** (requires `bash-completion` v2):
+**Bash** (requires `bash-completion` v2 and git completions):
 
 ```bash
 # Install bash-completion first (if not already installed)
@@ -133,15 +133,27 @@ brew install bash-completion@2
 # Ubuntu/Debian:
 sudo apt install bash-completion
 
+# Ensure git's bash completion is enabled (usually installed with git)
 # Then enable gtr completions:
 echo'source /path/to/git-worktree-runner/completions/gtr.bash'>>~/.bashrc
 source~/.bashrc
 ```
 
-**Zsh:**
+**Zsh** (requires git's zsh completion):
 
 ```bash
-echo'source /path/to/git-worktree-runner/completions/_gtr'>>~/.zshrc
+# Add completion directory to fpath and enable
+mkdir -p ~/.zsh/completions
+cp /path/to/git-worktree-runner/completions/_gtr ~/.zsh/completions/
+
+# Add to ~/.zshrc (if not already there):
+cat >>~/.zshrc <<'EOF'
+# Enable completions
+fpath=(~/.zsh/completions $fpath)
+autoload -Uz compinit && compinit
+EOF
+
+source~/.zshrc
 ```
 
 **Fish:**

completions/_gtr

@@ -1,7 +1,14 @@
-#compdef git-gtr
+#compdef _git-gtr git-gtr
+
+# Register gtr as a git subcommand for completion
+zstyle ':completion:*:*:git:*' user-commands gtr:'Git worktree management'
+
 # Zsh completion for git gtr
 
 _git-gtr(){
+ # Note: When called via 'git gtr', the words array is [git, gtr, <command>, ...]
+ # This matches how git's completion system passes context to subcommand completions
+
  local -a commands
  commands=(
  'new:Create a new worktree'
@@ -25,10 +32,12 @@ _git-gtr(){
  # Add special ID '1' for main repo
  all_options=("1" "${branches[@]}")
 
- if (( CURRENT == 2 )); then
+ # Complete the gtr subcommand (new, go, editor, etc.)
+ if (( CURRENT == 3 )); then
  _describe 'commands' commands
- elif (( CURRENT == 3 )); then
- case "$words[2]" in
+ # Complete arguments to the subcommand
+ elif (( CURRENT == 4 )); then
+ case "$words[3]" in
  go|editor|ai|rm)
  _describe 'branch names' all_options
  ;
@@ -46,16 +55,17 @@ _git-gtr(){
  _values 'config action' get set add unset
  ;
  esac
- elif (( CURRENT >= 4 )); then
- case "$words[2]" in
+ # Complete subsequent arguments
+ elif (( CURRENT >= 5 )); then
+ case "$words[3]" in
  rm)
  _arguments \
  '--delete-branch[Delete branch]' \
  '--force[Force removal even if dirty]' \
  '--yes[Non-interactive mode]'
  ;
  config)
- case "$words[3]" in
+ case "$words[4]" in
  get|set|add|unset)
  _values 'config key' \
  'gtr.worktrees.dir' \

completions/gtr.bash

@@ -1,5 +1,17 @@
 #!/bin/bash
 # Bash completion for git gtr
+#
+# Prerequisites:
+# - bash-completion v2+ must be installed
+# - Git's bash completion must be enabled
+#
+# This completion integrates with git's completion system by defining a _git_<subcommand>
+# function, which git's completion framework automatically discovers and calls when
+# completing "git gtr ..." commands.
+#
+# Installation:
+# Add to your ~/.bashrc:
+# source /path/to/git-worktree-runner/completions/gtr.bash
 
 _git_gtr(){
 local cur prev words cword

completions/gtr.fish

@@ -1,4 +1,13 @@
 # Fish completion for git gtr
+#
+# This completion integrates with fish's completion system by registering completions
+# for the "git" command with custom predicates that detect "git gtr" usage.
+#
+# Installation:
+# Symlink to fish's completions directory:
+# ln -s /path/to/git-worktree-runner/completions/gtr.fish ~/.config/fish/completions/
+# Then reload fish:
+# exec fish
 
 # Helper function to check if we're in 'git gtr' context
 function __fish_git_gtr_needs_command