git completion on zsh not listing ambiguous options (on macOS)

My machine is a M1 Mac mini running Big Sur.

I am trying to get git completion to work in the default terminal which uses a zsh shell.

This is what I am trying and expecting. Screenshot below.

I am able to get completion to work, but not exactly as described here.

Basically, if I type git cheTab that directly converts into git checkout instead of giving/listing the options of all the git commands starting with "che" (as shown in the screenshot above.)

Any further presses of Tab simply result in cycling through various branches, but the checkout doesn't change at all.

I have tried multiple ways like

• using zsh completion settings
• doing git completion settings
• and a few others I could find.

But none seem to work..

What am I doing wrong?

(by the way, I am ok even if the helpful suggestions (in above screenshot) are not displayed. But the completion should allow me to see a list of all possible ambiguous options and to cycle through them.)

Did you install Git through Homebrew? If so, then it also installed the completion bundled with Git, which is a simple port of its Bash completion, which then overrides Zsh's own much more sophisticated Git completion.

At least two issues and two PRs have been filed with Homebrew to make installing the completion shipped with the Git formula to be optional or remove it altogether, but its maintainer refuses to do so, because he feels using this Bash-style completion in Zsh is good enough for him. His argument is basically that since it ships with Git, it's the official completion and it should override Zsh's own (much better) Git completion. As to why this inferior completion is even maintained in the Git repo, when the Git manual itself recommends using Zsh's completion instead, I have no idea. I guess that's open source for you. 🤷🏽‍♂️

The only reliable way I've found to work around this is to put the following line in one's .zshrc file:

rm -f $HOMEBREW_PREFIX/share/zsh/site-functions/_git

This will cause Zsh's own completion function for Git to be used instead, which gives the much nicer output in the screenshot you posted.