fix: resolve gtr/coreutils naming conflict and add cd completions

[helizaga]

Summary

Closes #124

• Reverse binary relationship: bin/git-gtr is now the main entry point (sources libs, contains main() dispatcher). bin/gtr becomes a thin convenience wrapper. This allows the Homebrew formula to drop bin.install "bin/gtr", eliminating the conflict with coreutils gtr (GNU tr).

• Add --as flag to git gtr init: Users with coreutils can pick a non-conflicting shell function name:

  eval "$(git gtr init zsh --as gwtr)"
  gwtr cd my-feature  # no conflict with GNU tr

• Add cd completions to init output: All three shells (bash, zsh, fish) now complete cd as a subcommand with worktree names via git gtr list --porcelain.

• 26 new BATS tests for the init command (262 total, all passing).

Homebrew formula follow-up

The Homebrew formula in coderabbitai/homebrew-tap needs a separate update to remove bin.install "bin/gtr" — the binary reversal in this PR makes that safe to do.

Test plan

• bats tests/init.bats — 26 new tests pass
• bats tests/ — all 262 tests pass
• ./scripts/generate-completions.sh --check — completions in sync
• shellcheck bin/gtr bin/git-gtr — clean
• Verified both install paths work (regular symlink + simulated Homebrew Cellar)
• Installed coreutils, confirmed before/after: conflict reproduced then resolved
• Manual: eval "$(git gtr init zsh --as gwtr)" then gwtr cd <tab> completes worktrees

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added --as option to init to create a custom shell function name and avoid command collisions
  • Primary CLI now exposes a stable git-gtr entry with a lightweight gtr wrapper; shell completions updated to support init/--as across bash, zsh, and fish

• Documentation

  • Updated init help, README notes, and examples to document --as and conflict-resolution workflows

• Tests

  • Added tests covering init behavior, validation, completions, and error cases

[coderabbitai]

Walkthrough

Reclassifies binaries so bin/git-gtr is the main entrypoint (full dispatcher) and bin/gtr is a lightweight exec wrapper. Adds --as <name> to init (validation, shell-specific wrappers, completions), updates docs/completions, and adds tests for init behavior and validation.

Changes

Cohort / File(s)	Summary
Binary entrypoint change bin/git-gtr, bin/gtr	bin/git-gtr converted to the primary, self-contained Bash dispatcher (strict mode, GTR_VERSION, main dispatcher). bin/gtr reduced to a thin wrapper that locates and execs git-gtr.
Init command & helpers lib/commands/init.sh, lib/commands/help.sh	init now supports --as <name> with name validation; emits shell-specific function wrappers and completions for bash/zsh/fish; help text updated to document --as.
Completions & generators completions/_git-gtr, completions/git-gtr.fish, completions/gtr.bash, scripts/generate-completions.sh	Splits completion/init handling, adds --as/-l option completion across shells, and updates completion generation logic to expose the new flag and cd/worktree completions.
Docs & repo notes CLAUDE.md, CONTRIBUTING.md, README.md	Reflect binary role swap, document the --as option and a note about avoiding conflicts with existing gtr (e.g., GNU tr).
Tests tests/init.bats	New comprehensive bats tests for init covering default names, --as behavior, validation rules, cd completions, error handling, and passthrough behavior.

Sequence Diagram(s)

sequenceDiagram
    participant UserShell as "User Shell"
    participant GTR as "bin/gtr"
    participant GitGTR as "bin/git-gtr"
    participant ShellInit as "Shell (init output)"

    UserShell->>GTR: run `gtr ...` or `git gtr ...`
    GTR->>GitGTR: exec ./git-gtr "$@"
    GitGTR->>GitGTR: source libs, load commands
    alt command == init
        GitGTR->>ShellInit: emit shell-specific function (with --as if provided)
        ShellInit-->>UserShell: function code printed for eval
    else other command
        GitGTR->>GitGTR: dispatch to cmd_* handler
        GitGTR-->>UserShell: command result / exit
    end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Poem

🐰 I swapped the doors and tuned the bell,

git-gtr now runs the show quite well.
Say --as if GNU tr should roam,
A tiny wrapper calls it home.
Hops of joy — completions bloom! ✨

🚥 Pre-merge checks | ✅ 5 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 36.36% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately summarizes the main changes: resolving the gtr/coreutils naming conflict and adding cd completions, which are the primary objectives of the PR.
Linked Issues check	✅ Passed	All four key objectives from issue #124 are implemented: (1) binary relationship reversed to avoid gtr conflict [bin/git-gtr, bin/gtr], (2) --as flag added for custom function names [lib/commands/init.sh, completions], (3) cd completions added with worktree sourcing [lib/commands/init.sh, tests], (4) user-friendly approach provided [README.md, help].
Out of Scope Changes check	✅ Passed	All changes are directly related to resolving the naming conflict and adding cd completions; no unrelated modifications detected. Documentation updates (CLAUDE.md, CONTRIBUTING.md, README.md, help.sh) and completion generators support the core changes.
Merge Conflict Detection	✅ Passed	✅ No merge conflicts detected when merging into main

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/gtr-coreutils-conflict

---

No actionable comments were generated in the recent review. 🎉

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

scripts/generate-completions.sh (1)

611-629: ⚠️ Potential issue | 🟡 Minor

Add a case for gtr.ui.color to provide a meaningful description.

The gtr.ui.color key falls through to the default case (line 627), which just echoes the key name as the description. This results in unhelpful completion output in Fish.

📝 Suggested fix

       gtr.hook.postCd)      desc="Post-cd hook (shell integration only)" ;;
+      gtr.ui.color)         desc="Color output mode (auto, always, never)" ;;
       *)                    desc="$key" ;;

🤖 Fix all issues with AI agents

In `@bin/git-gtr`:
- Around line 17-24: In resolve_script_dir(), the test [[ $src != /* ]] leaves
$src unquoted which can break on spaces or glob chars; change that check to use
the quoted variable (i.e., [[ "$src" != /* ]]) so the symlink resolution handles
paths with spaces or special chars correctly and remains consistent with the
"always quote variables" guideline.

In `@completions/git-gtr.fish`:
- Line 143: Replace the non-descriptive description string 'gtr.ui.color' with a
user-friendly explanation for the gtr.ui.color setting (refer to the
gtr.ui.color key in the diff), e.g. "Color used for UI elements" or "UI theme
color (hex or name)"; update the single-quoted description to clearly state what
the setting controls and any expected format so users understand its purpose and
valid values.