[v2,1/1] doc: Change zsh git completion file name
diff mbox series

Message ID 3f994f3b9a49c42bb8b605459817e54479327dc7.1570816467.git.gitgitgadget@gmail.com
State New
Headers show
Series
  • doc: Add a note about ~/.zsh/_git file
Related show

Commit Message

Johannes Schindelin via GitGitGadget Oct. 11, 2019, 5:54 p.m. UTC
From: Maxim Belsky <public.belsky@gmail.com>

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 <public.belsky@gmail.com>
Helped-by: Johannes Schindelin <Johannes.Schindelin@gmx.de>
Helped-by: Junio C Hamano <gitster@pobox.com>
---
 contrib/completion/git-completion.zsh | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

Comments

Junio C Hamano Oct. 12, 2019, 1:35 a.m. UTC | #1
"Maxim Belsky via GitGitGadget" <gitgitgadget@gmail.com> writes:

> Signed-off-by: Maxim Belsky <public.belsky@gmail.com>
> Helped-by: Johannes Schindelin <Johannes.Schindelin@gmx.de>
> Helped-by: Junio C Hamano <gitster@pobox.com>

No need to resend (as I'll fix it up locally while queuing), but
your sign-off comes last, as we keep these things chronological.
With help from others, you wrote the patch and finally signed it off
to be applied.

Thanks for working on this.
SZEDER Gábor Oct. 14, 2019, 11:44 p.m. UTC | #2
On Fri, Oct 11, 2019 at 10:54:28AM -0700, Maxim Belsky via GitGitGadget wrote:
> From: Maxim Belsky <public.belsky@gmail.com>
> 
> 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 <public.belsky@gmail.com>
> Helped-by: Johannes Schindelin <Johannes.Schindelin@gmx.de>
> Helped-by: Junio C Hamano <gitster@pobox.com>
> ---
>  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.
Junio C Hamano Oct. 15, 2019, 2:07 a.m. UTC | #3
SZEDER Gábor <szeder.dev@gmail.com> writes:

>> -# 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:
> ...
> 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:

Thanks for a dose of sanity.  My "Helped-by" was about phrasing and
had nothing with the name of the file, so it should be fixable
without invalidating it ;-)

> -# 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

    # The recommended way to install this script is to make a copy of it in
    # '~/.zsh/' directory as '~/.zsh/_git' and then add the following

Patch
diff mbox series

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
+# to your ~/.zshrc file:
 #
 #  fpath=(~/.zsh $fpath)