Suggestion: add docs for zsh completions

[OliverJAsh]

Out of the box, Zsh completions don't work as you would expect.

Given a fresh install:

brew install zsh
brew install git
brew install hub

# Workaround to fix bug with hub completions.
# hub completions only work when this alias is set.
# https://github.com/github/hub/issues/1792#issuecomment-403413131
alias git=hub

When I type git pull-<tab>, it successfully completes to git pull-request.

However, completion does not work for subcommand arguments. For example, when I type git pull-request -<tab>, the arguments do not complete.

After some digging, I discovered that I had two sets of Zsh completions for Git (using the setup above, which I believe is the route most people will take):

• Git's official completions (e.g. /usr/local/share/zsh/site-functions/_git)
• Zsh's official Git completions (e.g. /usr/local/Cellar/zsh/5.6.2_1/share/zsh/functions/_git)

Both of these were on my $fpath.

I then discovered that the author of the Hub Zsh completions seems to advise the usage of Zsh's official Git completions, rather than Git's official completions: https://github.com/github/hub/pull/295#issuecomment-14324233

I removed Git's official completions with rm /usr/local/share/zsh/site-functions/_git and then Hub Zsh completions seemed to work as expected. That is, when I type git pull-request -<tab>, arguments do complete.

I would like to suggest that we clearly document this caveat—Hub Zsh completions only seem to fully work when using Zsh's official Git completions, rather than Git's official completions—along with instructions for how to use Zsh's official Git completions instead.

/cc @goodell

[mislav]

Thank you for reporting! Due to the nature of hub extending git, our completions (both zsh and bash) might be a bit of a mess at the moment, and your research helps greatly. ✨

[OliverJAsh]

I created a PR to improve the docs: https://github.com/github/hub/pull/1962