macOS 10.15 shell completion documentation seems wrong

[realnc]

• [ yes] are reporting a bug others will be able to reproduce and not asking a question. If you're not sure or want to ask a question do so on our Discourse: https://discourse.brew.sh
• [ yes] ran a brew command and reproduced the problem with multiple formulae? If it's a problem with a single, official formula (not cask) please file this issue at Homebrew/homebrew-core: https://github.com/Homebrew/homebrew-core/issues/new/choose. If it's a brew cask problem please file this issue at https://github.com/Homebrew/homebrew-cask/issues/new/choose. If it's a tap (e.g. Homebrew/homebrew-php) problem please file this issue at the tap.
• [yes ] ran brew update and can still reproduce the problem?
• [yes ] ran brew doctor, fixed all issues and can still reproduce the problem?
• [yes ] ran brew config and brew doctor and included their output with your issue?

I installed macOS 10.15 ("Catalina") cleanly from install media on an empty HD, not as an upgrade to an existing macOS installation. I installed XCode 11.1 and did xcode-select --install. After that, I installed homebrew with the command shown at https://brew.sh.

Then I followed the instructions at https://docs.brew.sh/Shell-Completion to enable shell completion. I created ~/.zshrc and added this to it:

if type brew &>/dev/null; then
  FPATH=$(brew --prefix)/share/zsh/site-functions:$FPATH
fi

Logged out and in again, but completion isn't working. I ran this command as suggested in the guide:

rm -f ~/.zcompdump; compinit

But all this does is print an error message:

zsh: command not found: compinit

Again, this is a clean install of 10.15. Nothing tweaked, and nothing installed other than Xcode.

Output of brew config:

HOMEBREW_VERSION: 2.1.13
ORIGIN: https://github.com/Homebrew/brew
HEAD: aa043c1d678afd26f50156a83417c296cb9d5a4b
Last commit: 4 days ago
Core tap ORIGIN: https://github.com/Homebrew/homebrew-core
Core tap HEAD: 61d6ab98ec1d6e8f4e481e8f8563f3c0b0c790b5
Core tap last commit: 4 hours ago
HOMEBREW_PREFIX: /usr/local
CPU: dual-core 64-bit sandybridge
Homebrew Ruby: 2.6.3 => /System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/bin/ruby
Clang: 11.0 build 1100
Git: 2.21.0 => /Applications/Xcode.app/Contents/Developer/usr/bin/git
Curl: 7.64.1 => /usr/bin/curl
macOS: 10.15-x86_64
CLT: 11.0.0.0.1.1567737322
Xcode: 11.1
CLT headers: 11.0.0.0.1.1567737322

Output of brew doctor:

Your system is ready to brew.

[dawidd6]

Please try running these commands:

autoload -Uz compinit
compinit

[realnc]

Please try running these commands:

autoload -Uz compinit
compinit

Yep, this enabled completion. But it needs to be done on each login, so I added them to my ~/.zshrc. Not sure if these commands need to come before or after the existing one.

[dawidd6]

After:

if type brew &>/dev/null; then
  FPATH=$(brew --prefix)/share/zsh/site-functions:$FPATH
fi

[MikeMcQuaid]

It's expected that you'll need to enable ZSH completion for this to work.

[realnc]

It's expected that you'll need to enable ZSH completion for this to work.

Note that I reported this as a documentation bug for https://docs.brew.sh/Shell-Completion. You say it's expected to have those commands in .zshrc, but the documentation doesn't mention that.

[realnc]

@MikeMcQuaid

Ping?

[MikeMcQuaid]

@realnc I'd like to see more than one person experience this problem before I consider this a bug with the documentation.

[Vernadsky]

Add this to your .zshrc and it works:

if type brew &>/dev/null; then
  FPATH=$(brew --prefix)/share/zsh/site-functions:$FPATH

  autoload -Uz compinit
  compinit
fi

The autoload and compinit commands are required for it to work and are missing from the instructions that you get after installing zsh-completions with HomeBrew.

In some cases you have to force a rebuild with:

rm -f ~/.zcompdump; compinit

Tested on macOS Catalina 10.15.1

[MikeMcQuaid]

For anyone watching: should be resolved in #7065.