Subject: Re: [PATCH v2 1/1] doc: Change zsh git completion file name

From: SZEDER Gábor <[email-masked]>
Date: Tue, 15 Oct 2019 01:44:39 +0200

On Fri, Oct 11, 2019 at 10:54:28AM -0700, Maxim Belsky via GitGitGadget wrote:
> From: Maxim Belsky <[email-masked]>
> 
> The original comment does not describe type of ~/.zsh/_git explicitly
> and zsh does not warn or fail if a user create it as a dictionary.
> So unexperienced users could be misled by the original comment.
> 
> There is a small update to clarify it.
> 
> Signed-off-by: Maxim Belsky <[email-masked]>
> Helped-by: Johannes Schindelin <[email-masked]>
> Helped-by: Junio C Hamano <[email-masked]>
> ---
>  contrib/completion/git-completion.zsh | 5 +++--
>  1 file changed, 3 insertions(+), 2 deletions(-)
> 
> diff --git a/contrib/completion/git-completion.zsh b/contrib/completion/git-completion.zsh
> index 886bf95d1f..eef4eff53d 100644
> --- a/contrib/completion/git-completion.zsh
> +++ b/contrib/completion/git-completion.zsh
> @@ -11,8 +11,9 @@
>  #
>  #  zstyle ':completion:*:*:git:*' script ~/.git-completion.zsh
>  #
> -# The recommended way to install this script is to copy to '~/.zsh/_git', and
> -# then add the following to your ~/.zshrc file:
> +# The recommended way to install this script is to make a copy of it in
> +# ~/.zsh/ directory as ~/.zsh/git-completion.zsh and then add the following

These updated instructions don't work for me, following them gives me
zsh's git completion instead of ours:

  $ ls -l /etc/bash_completion.d/git
  -rwxr-xr-x 1 root root 72165 Oct 15 01:27 /etc/bash_completion.d/git
  $ ls -l ~/.zsh/
  total 8
  -rw-r--r-- 1 szeder szeder 6013 Oct 15 01:27 git-completion.zsh
  $ cat ~/.zshrc 
  # Use modern completion system
  autoload -Uz compinit
  compinit
  
  fpath=(~/.zsh $fpath)
  $ zsh
  % git init --<TAB>
  --bare              -- create a bare repository
  --quiet             -- do not print any results to stdout
  --separate-git-dir  -- create git dir elsewhere and link it using the gitdir
  --shared            -- share repository amongst several users
  --template          -- directory to use as a template for the object databas

That's clearly zsh's fancy completion.

As a non-zsh user I had the impression that it's a well-established
convention that the completion script of a command for zsh is called
'_command', see e.g. all the scripts in:

  https://github.com/zsh-users/zsh-completions/tree/master/src

Instructing users to copy our completion script to
'~/.zsh/git-completion.zsh' goes against this convention.

More importantly, it appears that this is more than a mere convention,
maybe a requirement even; at least renaming our zsh completion script
to follow the convention (IOW following the current install
instructions) makes it work all of a sudden:

  $ mv .zsh/git-completion.zsh .zsh/_git
  $ zsh
  % git init --
  --                      --no-separate-git-dir   --shared 
  --bare                  --no-template           --template=
  --no-bare               --quiet                 
  --no-quiet              --separate-git-dir=     

Now that's our Bash completion script used by zsh.