Migrate to git gtr subcommand (resolves coreutils conflict) (#19)

Author: helizaga

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,92 @@
+# Pull Request
+
+## Description
+
+<!-- A clear and concise description of what this PR does -->
+
+## Motivation
+
+<!-- Why is this change needed? What problem does it solve? -->
+
+Fixes # (issue)
+
+## Type of Change
+
+<!-- Check all that apply -->
+
+- [ ] Bug fix (non-breaking change that fixes an issue)
+- [ ] New feature (non-breaking change that adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation update
+- [ ] Code refactoring (no functional changes)
+- [ ] Other (please describe):
+
+## Testing
+
+<!-- Describe the tests you ran to verify your changes -->
+
+### Manual Testing Checklist
+
+**Tested on:**
+
+- [ ] macOS
+- [ ] Linux (specify distro: **\*\***\_**\*\***)
+- [ ] Windows (Git Bash)
+
+**Core functionality tested:**
+
+- [ ] `git gtr new <branch>` - Create worktree
+- [ ] `git gtr go <branch>` - Navigate to worktree
+- [ ] `git gtr editor <branch>` - Open in editor (if applicable)
+- [ ] `git gtr ai <branch>` - Start AI tool (if applicable)
+- [ ] `git gtr rm <branch>` - Remove worktree
+- [ ] `git gtr list` - List worktrees
+- [ ] `git gtr config` - Configuration commands (if applicable)
+- [ ] Other commands affected by this change: **\*\***\_\_**\*\***
+
+### Test Steps
+
+<!-- Provide detailed steps to reproduce/test your changes -->
+
+1.
+2.
+3.
+
+**Expected behavior:**
+
+**Actual behavior:**
+
+## Breaking Changes
+
+<!-- If this introduces breaking changes, describe: -->
+<!-- - What breaks -->
+<!-- - Why it's necessary -->
+<!-- - Migration path for users -->
+
+- [ ] This PR introduces breaking changes
+- [ ] I have discussed this in an issue first
+- [ ] Migration guide is included in documentation
+
+## Checklist
+
+Before submitting this PR, please check:
+
+- [ ] I have read [CONTRIBUTING.md](../CONTRIBUTING.md)
+- [ ] My code follows the project's style guidelines
+- [ ] I have performed manual testing on at least one platform
+- [ ] I have updated documentation (README.md, CLAUDE.md, etc.) if needed
+- [ ] My changes work on multiple platforms (or I've noted platform-specific behavior)
+- [ ] I have added/updated shell completions (if adding new commands or flags)
+- [ ] I have tested with both `git gtr` (production) and `./bin/gtr` (development)
+- [ ] No new external dependencies are introduced (Bash + git only)
+- [ ] All existing functionality still works
+
+## Additional Context
+
+<!-- Add any other context, screenshots, or information about the PR here -->
+
+---
+
+## License Acknowledgment
+
+By submitting this pull request, I confirm that my contribution is made under the terms of the [Apache License 2.0](../LICENSE.txt).

.github/instructions/completions.instructions.md

@@ -1,66 +1,77 @@
 ---
-applyTo: completions/gtr.bash, completions/_gtr, completions/gtr.fish
+applyTo: completions/gtr.bash, completions/_git-gtr, completions/gtr.fish
 ---
 
 # Completions Instructions
 
 ## Overview
 
-Shell completions provide tab-completion for `gtr` commands, flags, branches, and adapter names across Bash, Zsh, and Fish shells.
+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., `gtr new-command`)
+- 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/_gtr`** - Zsh completion (uses Zsh completion system)
+- **`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`, `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 `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
-gtr <TAB>                    # Should show commands
-gtr new <TAB>                # Should show flags
-gtr open <TAB>               # Should show branches
-gtr open --editor <TAB>      # Should show editor names
-
-# Zsh - fpath must include completions directory
-fpath=(completions $fpath)
-autoload -U compinit && compinit
-gtr <TAB>
+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/
-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 `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
 
@@ -71,15 +82,15 @@ When adding an editor or AI adapter:
 - Update `_gtr_editors` array or case statement
 - Update flag completion for `--editor` in `open` command
 
-**Zsh** (`completions/_gtr`):
+**Zsh** (`completions/_git-gtr`):
 
 - Update `_arguments` completion specs for `--editor` or `--ai`
 - Use `_values` or `_alternative` for adapter names
 
 **Fish** (`completions/gtr.fish`):
 
-- Update `complete -c gtr` lines for editor/AI flags
-- List adapter names explicitly or parse from `gtr adapter` output
+- Update `complete -c git` lines for editor/AI flags
+- List adapter names explicitly or parse from `git gtr adapter` output
 
 ## Keep in Sync
 
@@ -92,7 +103,7 @@ The three completion files must stay synchronized:
 
 ## Examples
 
-**Adding a new command `gtr status`**:
+**Adding a new command `git gtr status`**:
 
 1. Add `status` to main command list in all three files
 2. Add flag completion if the command has flags
@@ -104,7 +115,7 @@ The three completion files must stay synchronized:
 2. Add `sublime` to editor list in all three completion files
 3. Update help text in `bin/gtr` (`cmd_help` function)
 4. Update README with installation instructions
-5. Test `gtr open --editor s<TAB>` completes to `sublime`
+5. Test `git gtr open --editor s<TAB>` completes to `sublime`
 
 ## Common Pitfalls
 
@@ -128,6 +139,6 @@ The three completion files must stay synchronized:
 
 ## Fish-Specific Notes
 
-- Uses declarative `complete -c gtr` syntax
-- Conditions can check previous arguments with `__fish_seen_subcommand_from`
+- Uses `complete -c git` with custom predicates (`__fish_git_gtr_needs_command`, `__fish_git_gtr_using_command`) to handle git subcommand context
+- Conditions can check previous arguments with custom functions to detect `git gtr` usage
 - Can call external commands for dynamic completion

.github/instructions/editor.instructions.md

@@ -29,7 +29,7 @@ editor_open() {
 **Also update**:
 
 - README.md (setup instructions)
-- All three completion files: `completions/gtr.bash`, `completions/_gtr`, `completions/gtr.fish`
+- All three completion files: `completions/gtr.bash`, `completions/_git-gtr`, `completions/gtr.fish`
 - Help text in `bin/gtr` (`cmd_help` function)
 
 ## Contract & Guidelines