gtr binary and shell function conflict with coreutils (GNU tr)

[fmal]

Summary

Two related issues when using git-gtr on a system with GNU coreutils installed via Homebrew.

Issues

1. gtr binary conflicts with coreutils

brew install coreutils provides /opt/homebrew/bin/gtr (GNU tr). Installing git-gtr via Homebrew fails to link because of this conflict:

$ brew link git-gtr
Error: Could not symlink bin/gtr
Target /opt/homebrew/bin/gtr
is a symlink belonging to coreutils.

This causes brew link to fail entirely, which also prevents the zsh/bash/fish completion files from being symlinked.

2. git gtr init zsh shadows coreutils gtr

Even without the binary conflict, eval "$(git gtr init zsh)" defines a gtr() shell function that shadows the coreutils gtr command. Additionally, gtr cd <tab> doesn't complete worktree names since cd is not listed in the completion file.

Workaround

My current workaround is to skip git gtr init zsh and define a custom function with completions (which gtr cd is currently missing):

if command -v git-gtr &> /dev/null; then
  function gcd {
    local dir
    dir="$(git gtr go "$@")" && cd "$dir"
  }

  function _gcd {
    local -a worktrees
    worktrees=("1" ${(f)"$(git gtr list --porcelain 2>/dev/null | cut -f2)"})
    _describe 'worktrees' worktrees
  }
  compdef _gcd gcd
fi

Suggested fixes

• Consider removing the gtr shorthand binary — git gtr already works as a git subcommand, and the shorthand conflicts with coreutils. The shell init could alias it for users who want it.
• Consider adding cd to the completion file, and using git gtr list --porcelain instead of git branch for worktree name completions

Environment

• macOS (Apple Silicon)
• Homebrew, with coreutils installed
• git-gtr 2.3.0

[helizaga]

Thanks for the detailed report @fmal — all three issues are addressed in #125:

1. Homebrew binary conflict → fixed

The binary relationship is reversed: bin/git-gtr is now the main entry point (sources libs, contains main()), and bin/gtr is just a thin convenience wrapper. This means the Homebrew formula can drop bin.install "bin/gtr" entirely — no more conflict with coreutils. A follow-up PR to the tap repo will make that change.

2. Shell function shadows coreutils → --as flag

git gtr init now accepts --as <name> to choose a custom function name:

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

The default remains gtr for backwards compatibility, but users with coreutils can pick any valid identifier.

3. cd completions → added

The init output now includes proper cd completions for all three shells. Worktree names are completed using git gtr list --porcelain (shows only actual worktrees, not all branches). The special ID 1 (main repo) is also included.

This should match the experience you described in your workaround, but built-in.

[fmal]

@helizaga awesome!! ❤️ thanks so much for addressing this so quick, can't wait to update! 🚀

[helizaga]

just cut a release!

[fmal]

@helizaga thanks! works like a charm 💯 could you also drop bin.install "bin/gtr" in the homebrew formula?

[WickyNilliams]

I just tried to install gtr and hit the same issue. brew link fails and git-gtr is not in PATH. I think the homebrew formula needs updating as @fmal suggests?

To get it working with git i had to manually symlink:

ln -s /opt/homebrew/Cellar/git-gtr/2.4.0/bin/git-gtr /opt/homebrew/bin/git-gtr

which feels extremely hacky!

[nkovacic]

Had the same issue, reverted to git clone install (without Brew).

[nkovacic]

@helizaga Any update on this issue? It is still happening and making the rollout of git-gtr as the main git worktree utility more difficult on MacOS.