Add shell helper for easier worktree directory switching

[echarrod]

Problem

Switching to a worktree directory currently requires a verbose subshell pattern:

cd "$(git gtr go feature/user-auth)"

This is cumbersome for frequent use.

Proposal

Provide a built-in shell helper (e.g. a function or alias) that allows something like:

gtr cd feature/user-auth

Why not git gtr cd?

Since git gtr runs as a subprocess, it cannot change the parent shell's working directory. A true cd command would need to be implemented as a shell function rather than a script command.

Possible approaches

1. Ship a shell function that users source in their shell profile (.bashrc/.zshrc/config.fish), e.g.:

   gtr() {
     if [ "$1" = "cd" ]; then
       shift
       local dir
       dir="$(git gtr go "$@")" && cd "$dir"
     else
       command git gtr "$@"
     fi
   }

2. Add a git gtr shell-helper command that prints the function definition so users can eval/source it:

   # In .bashrc/.zshrc:
   eval "$(git gtr shell-helper bash)"

   Similar to how tools like direnv, fnm, and zoxide handle shell integration.

3. Document a recommended alias in the README, e.g.:

   alias gcd='cd "$(git gtr go"'

Option 2 feels most aligned with the project's existing patterns (similar to git gtr completion).

[traycerai]

Plan

Observations

The codebase follows a well-established pattern for shell integration through the existing completion command (file:bin/gtr lines 1495-1555). The project uses a single bash script (file:bin/gtr) with a command dispatcher pattern. The go command already exists to print worktree paths, but requires verbose subshell syntax cd "$(git gtr go branch)". The issue proposes adding a shell-helper command following the same pattern as completion, which generates shell-specific functions that users can eval in their shell profiles.

Approach

Following the established completion command pattern, implement a new shell-helper command that generates shell-specific wrapper functions. The wrapper intercepts gtr cd <branch> calls and translates them to cd "$(git gtr go <branch>)", while passing all other commands through to the actual git gtr binary. This approach aligns with tools like direnv, fnm, and zoxide mentioned in the issue, and maintains consistency with the existing codebase architecture.

Implementation Steps

1. Add Shell Helper Command Function

In file:bin/gtr, add a new cmd_shell_helper function after the cmd_completion function (around line 1555):

Function Structure:

• Accept shell type as first argument (bash, zsh, fish)
• Generate shell-specific wrapper function code for each shell
• Include help text when no arguments or --help is provided
• Return error for unsupported shells

Shell-Specific Function Logic:

• Bash/Zsh: Create a gtr() function that:

  • Checks if first argument is cd
  • If yes: shifts arguments, calls git gtr go "$@", captures output, and executes cd to that directory
  • If no: passes all arguments to command git gtr "$@"
  • Handles error cases (e.g., when git gtr go fails)

• Fish: Create a gtr function that:

  • Uses fish syntax with if statements
  • Checks $argv[1] for cd command
  • Uses set -e argv[1] to shift arguments
  • Captures output with command substitution
  • Falls back to command git gtr $argv for other commands

Error Handling:

• Ensure the wrapper function only changes directory if git gtr go succeeds
• Preserve exit codes from the underlying git gtr command
• Handle edge cases like empty arguments or invalid branch names

2. Update Main Command Dispatcher

In file:bin/gtr around line 112, add a new case entry in the main dispatcher:

shell-helper)
  cmd_shell_helper "$@"
  ;;

Position it near the completion command entry to maintain logical grouping of shell integration commands.

3. Update Help Documentation

In file:bin/gtr, update the cmd_help function (around line 1774) to include the new command:

Add to the "SETUP & MAINTENANCE" section:

• Command name: shell-helper <shell>
• Description: Generate shell wrapper function for easier directory switching
• Usage example: eval "$(git gtr shell-helper bash)"
• Note about adding to shell profile (.bashrc, .zshrc, config.fish)

4. Update Shell Completions

Add completion support for the new shell-helper command in all three completion files:

file:completions/gtr.bash (around line 70):

• Add shell-helper to the command list in the first completion block
• Add a case for shell-helper that completes with shell names (bash, zsh, fish)

file:completions/_git-gtr (around line 44):

• Add 'shell-helper:Generate shell wrapper function' to the commands array
• Add completion case for shell names when command is shell-helper

file:completions/git-gtr.fish (around line 49):

• Add completion line: complete -f -c git -n '__fish_git_gtr_needs_command' -a shell-helper -d 'Generate shell wrapper function'
• Add completion for shell types: complete -f -c git -n '__fish_git_gtr_using_command shell-helper' -a 'bash zsh fish' -d 'Shell type'

5. Update README Documentation

In file:README.md, add a new section after "Shell Completions (Optional)" (around line 367):

New Section: "Shell Helper for Directory Switching (Optional)"

• Explain the problem: verbose cd "$(git gtr go branch)" syntax
• Show the solution: gtr cd branch after installing the helper
• Provide installation instructions for each shell:
  • Bash: Add eval "$(git gtr shell-helper bash)" to ~/.bashrc
  • Zsh: Add eval "$(git gtr shell-helper zsh)" to ~/.zshrc
  • Fish: Add eval (git gtr shell-helper fish) to ~/.config/fish/config.fish
• Include usage examples comparing old vs new syntax
• Note that this is optional and the original cd "$(git gtr go ...)" syntax still works

6. Update CHANGELOG

In file:CHANGELOG.md, add an entry for the new feature:

• Version: Next unreleased version
• Category: Added
• Description: New shell-helper command for easier worktree directory switching with gtr cd <branch> syntax

Implementation Flow

sequenceDiagram
    participant User
    participant Shell
    participant gtr_wrapper as gtr() wrapper
    participant git_gtr as git gtr binary

    Note over User,Shell: One-time setup
    User->>Shell: eval "$(git gtr shell-helper bash)"
    Shell->>git_gtr: Execute shell-helper command
    git_gtr-->>Shell: Return wrapper function code
    Shell->>Shell: Define gtr() function

    Note over User,Shell: Daily usage
    User->>Shell: gtr cd feature-auth
    Shell->>gtr_wrapper: Invoke wrapper function
    gtr_wrapper->>git_gtr: git gtr go feature-auth
    git_gtr-->>gtr_wrapper: /path/to/worktree
    gtr_wrapper->>Shell: cd /path/to/worktree
    Shell-->>User: Changed directory

    Note over User,Shell: Other commands pass through
    User->>Shell: gtr list
    Shell->>gtr_wrapper: Invoke wrapper function
    gtr_wrapper->>git_gtr: git gtr list
    git_gtr-->>User: Display worktree list

Loading

Testing Considerations

While not explicitly requested, consider these validation points:

• Test the generated wrapper function in each shell (bash, zsh, fish)
• Verify gtr cd changes directory correctly
• Verify other commands still work through the wrapper
• Test error handling when branch doesn't exist
• Ensure the wrapper preserves exit codes
• Verify completion still works with the wrapper function installed

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase follows a well-established pattern for shell integration through the existing `completion` command (file:`bin/gtr` lines 1495-1555). The project uses a single bash script (file:`bin/gtr`) with a command dispatcher pattern. The `go` command already exists to print worktree paths, but requires verbose subshell syntax `cd "$(git gtr go branch)"`. The issue proposes adding a `shell-helper` command following the same pattern as `completion`, which generates shell-specific functions that users can eval in their shell profiles.

## Approach

Following the established `completion` command pattern, implement a new `shell-helper` command that generates shell-specific wrapper functions. The wrapper intercepts `gtr cd <branch>` calls and translates them to `cd "$(git gtr go <branch>)"`, while passing all other commands through to the actual `git gtr` binary. This approach aligns with tools like direnv, fnm, and zoxide mentioned in the issue, and maintains consistency with the existing codebase architecture.

## Implementation Steps

### 1. Add Shell Helper Command Function

In file:`bin/gtr`, add a new `cmd_shell_helper` function after the `cmd_completion` function (around line 1555):

**Function Structure:**
- Accept shell type as first argument (bash, zsh, fish)
- Generate shell-specific wrapper function code for each shell
- Include help text when no arguments or `--help` is provided
- Return error for unsupported shells

**Shell-Specific Function Logic:**
- **Bash/Zsh**: Create a `gtr()` function that:
  - Checks if first argument is `cd`
  - If yes: shifts arguments, calls `git gtr go "$@"`, captures output, and executes `cd` to that directory
  - If no: passes all arguments to `command git gtr "$@"`
  - Handles error cases (e.g., when `git gtr go` fails)

- **Fish**: Create a `gtr` function that:
  - Uses fish syntax with `if` statements
  - Checks `$argv[1]` for `cd` command
  - Uses `set -e argv[1]` to shift arguments
  - Captures output with command substitution
  - Falls back to `command git gtr $argv` for other commands

**Error Handling:**
- Ensure the wrapper function only changes directory if `git gtr go` succeeds
- Preserve exit codes from the underlying `git gtr` command
- Handle edge cases like empty arguments or invalid branch names

### 2. Update Main Command Dispatcher

In file:`bin/gtr` around line 112, add a new case entry in the main dispatcher:

```
shell-helper)
  cmd_shell_helper "$@"
  ;;
```

Position it near the `completion` command entry to maintain logical grouping of shell integration commands.

### 3. Update Help Documentation

In file:`bin/gtr`, update the `cmd_help` function (around line 1774) to include the new command:

**Add to the "SETUP & MAINTENANCE" section:**
- Command name: `shell-helper <shell>`
- Description: Generate shell wrapper function for easier directory switching
- Usage example: `eval "$(git gtr shell-helper bash)"`
- Note about adding to shell profile (`.bashrc`, `.zshrc`, `config.fish`)

### 4. Update Shell Completions

Add completion support for the new `shell-helper` command in all three completion files:

**file:`completions/gtr.bash`** (around line 70):
- Add `shell-helper` to the command list in the first completion block
- Add a case for `shell-helper` that completes with shell names (bash, zsh, fish)

**file:`completions/_git-gtr`** (around line 44):
- Add `'shell-helper:Generate shell wrapper function'` to the commands array
- Add completion case for shell names when command is `shell-helper`

**file:`completions/git-gtr.fish`** (around line 49):
- Add completion line: `complete -f -c git -n '__fish_git_gtr_needs_command' -a shell-helper -d 'Generate shell wrapper function'`
- Add completion for shell types: `complete -f -c git -n '__fish_git_gtr_using_command shell-helper' -a 'bash zsh fish' -d 'Shell type'`

### 5. Update README Documentation

In file:`README.md`, add a new section after "Shell Completions (Optional)" (around line 367):

**New Section: "Shell Helper for Directory Switching (Optional)"**
- Explain the problem: verbose `cd "$(git gtr go branch)"` syntax
- Show the solution: `gtr cd branch` after installing the helper
- Provide installation instructions for each shell:
  - Bash: Add `eval "$(git gtr shell-helper bash)"` to `~/.bashrc`
  - Zsh: Add `eval "$(git gtr shell-helper zsh)"` to `~/.zshrc`
  - Fish: Add `eval (git gtr shell-helper fish)` to `~/.config/fish/config.fish`
- Include usage examples comparing old vs new syntax
- Note that this is optional and the original `cd "$(git gtr go ...)"` syntax still works

### 6. Update CHANGELOG

In file:`CHANGELOG.md`, add an entry for the new feature:
- Version: Next unreleased version
- Category: Added
- Description: New `shell-helper` command for easier worktree directory switching with `gtr cd <branch>` syntax

## Implementation Flow

```mermaid
sequenceDiagram
    participant User
    participant Shell
    participant gtr_wrapper as gtr() wrapper
    participant git_gtr as git gtr binary

    Note over User,Shell: One-time setup
    User->>Shell: eval "$(git gtr shell-helper bash)"
    Shell->>git_gtr: Execute shell-helper command
    git_gtr-->>Shell: Return wrapper function code
    Shell->>Shell: Define gtr() function

    Note over User,Shell: Daily usage
    User->>Shell: gtr cd feature-auth
    Shell->>gtr_wrapper: Invoke wrapper function
    gtr_wrapper->>git_gtr: git gtr go feature-auth
    git_gtr-->>gtr_wrapper: /path/to/worktree
    gtr_wrapper->>Shell: cd /path/to/worktree
    Shell-->>User: Changed directory

    Note over User,Shell: Other commands pass through
    User->>Shell: gtr list
    Shell->>gtr_wrapper: Invoke wrapper function
    gtr_wrapper->>git_gtr: git gtr list
    git_gtr-->>User: Display worktree list
```

## Testing Considerations

While not explicitly requested, consider these validation points:
- Test the generated wrapper function in each shell (bash, zsh, fish)
- Verify `gtr cd` changes directory correctly
- Verify other commands still work through the wrapper
- Test error handling when branch doesn't exist
- Ensure the wrapper preserves exit codes
- Verify completion still works with the wrapper function installed

---

Execution Information

Branch: main
Commit: 923f580

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[echarrod]

Let me know if you think this is a good idea, if so I can have a go at implementing 👍