[PATCH 0/1] doc: Add a note about ~/.zsh/_git file

[PATCH 0/1] doc: Add a note about ~/.zsh/_git file

[Max Belsky via GitGitGadget]

Hey,

Today I've spent a few hours to understand why git-completion doesn't work
in my zsh shell. It was because I thought ~/.zsh/_git should be a dictionary
with git-completion.zsh file. 

I think this change may save some hours for someone else.

Maxim Belsky (1):
  doc: Change zsh git completion file name

 contrib/completion/git-completion.zsh | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)


base-commit: 4c86140027f4a0d2caaa3ab4bd8bfc5ce3c11c8a
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-367%2Fmbelsky%2Fpatch-1-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-367/mbelsky/patch-1-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/367
-- 
gitgitgadget

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

[Maxim Belsky via GitGitGadget]

From: Maxim Belsky <public.belsky@gmail.com>

Signed-off-by: Maxim Belsky <public.belsky@gmail.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..c0eca3ff25 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 copy to
+# '~/.zsh/.git-completion.zsh', and then add the following to your ~/.zshrc
+# file:
 #
 #  fpath=(~/.zsh $fpath)
 
-- 
gitgitgadget

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

[Johannes Schindelin]

Hi Maxim,


On Thu, 10 Oct 2019, Maxim Belsky via GitGitGadget wrote:

> From: Maxim Belsky <public.belsky@gmail.com>
>
> Signed-off-by: Maxim Belsky <public.belsky@gmail.com>

I totally agree with the patch, but only because I read a couple of
reports that users were struggling with this. Maybe add a couple of
reference points to the commit message, to describe how easy it is to
miss the fact that it needs to be a _file_, not a directory, and also
describe how `zsh` tells you that there is a problem (even if it does
not report a problem, that's a valuable piece of information for the
commit message).

Thanks,
Johannes
> ---
>  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..c0eca3ff25 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 copy to
> +# '~/.zsh/.git-completion.zsh', and then add the following to your ~/.zshrc
> +# file:
>  #
>  #  fpath=(~/.zsh $fpath)
>
> --
> gitgitgadget
>

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

[Junio C Hamano]

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

> On Thu, 10 Oct 2019, Maxim Belsky via GitGitGadget wrote:
>
>> From: Maxim Belsky <public.belsky@gmail.com>
>>
>> Signed-off-by: Maxim Belsky <public.belsky@gmail.com>
>
> I totally agree with the patch, but only because I read a couple of
> reports that users were struggling with this. Maybe add a couple of
> reference points to the commit message, to describe how easy it is to
> miss the fact that it needs to be a _file_, not a directory, and also
> describe how `zsh` tells you that there is a problem (even if it does
> not report a problem, that's a valuable piece of information for the
> commit message).

After reading the updated text, and then hearing many people cannot
get if the existing reference to ~/.zsh/_git is about a directory
(to which this should be added as one of the files in it) or a file,
I doubt that the updated text is clear enough for these people.

>> -# 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 copy to
>> +# '~/.zsh/.git-completion.zsh', and then add the following to your ~/.zshrc
>> +# file:

Perhaps making it absolutely clear by risking to be overly verbose,
like so?

    The recommended way to install this script is to make a copy of it
    in ~/.zsh/ directory as ~/.zsh/git-completion.zsh and then ...

If my attempt to be overly verbose and absolutely clear above is
giving a wrong piece of advice, then that would be an indication
that the original nor the updated text is clear enough, as they are
the primary sources of information on this matter I used to come up
with the suggestion ;-)

>>  #
>>  #  fpath=(~/.zsh $fpath)
>>
>> --
>> gitgitgadget
>>

[PATCH v2 0/1] doc: Add a note about ~/.zsh/_git file

[Max Belsky via GitGitGadget]

Hey,

Today I've spent a few hours to understand why git-completion doesn't work
in my zsh shell. It was because I thought ~/.zsh/_git should be a dictionary
with git-completion.zsh file. 

I think this change may save some hours for someone else.

Maxim Belsky (1):
  doc: Change zsh git completion file name

 contrib/completion/git-completion.zsh | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)


base-commit: 4c86140027f4a0d2caaa3ab4bd8bfc5ce3c11c8a
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-367%2Fmbelsky%2Fpatch-1-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-367/mbelsky/patch-1-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/367

Range-diff vs v1:

 1:  ae00e1e393 ! 1:  3f994f3b9a doc: Change zsh git completion file name
     @@ -2,7 +2,15 @@
      
          doc: Change zsh git completion file name
      
     +    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>
      
       diff --git a/contrib/completion/git-completion.zsh b/contrib/completion/git-completion.zsh
       --- a/contrib/completion/git-completion.zsh
     @@ -13,9 +21,9 @@
       #
      -# 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 copy to
     -+# '~/.zsh/.git-completion.zsh', 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)
       

-- 
gitgitgadget

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

[Maxim Belsky via GitGitGadget]

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

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

[Junio C Hamano]

"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.

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

[SZEDER Gábor]

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.

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

[Junio C Hamano]

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 v3 0/1] doc: Add a note about ~/.zsh/_git file

[Max Belsky via GitGitGadget]

Hey,

Today I've spent a few hours to understand why git-completion doesn't work
in my zsh shell. It was because I thought ~/.zsh/_git should be a dictionary
with git-completion.zsh file. 

I think this change may save some hours for someone else.

Maxim Belsky (1):
  doc: Change zsh git completion file name

 contrib/completion/git-completion.zsh | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)


base-commit: 108b97dc372828f0e72e56bbb40cae8e1e83ece6
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-367%2Fmbelsky%2Fpatch-1-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-367/mbelsky/patch-1-v3
Pull-Request: https://github.com/gitgitgadget/git/pull/367

Range-diff vs v2:

 1:  3f994f3b9a ! 1:  7919addea8 doc: Change zsh git completion file name
     @@ -8,9 +8,10 @@
      
          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>
     +    Helped-by: SZEDER Gábor <szeder.dev@gmail.com>
     +    Signed-off-by: Maxim Belsky <public.belsky@gmail.com>
      
       diff --git a/contrib/completion/git-completion.zsh b/contrib/completion/git-completion.zsh
       --- a/contrib/completion/git-completion.zsh
     @@ -22,8 +23,8 @@
      -# 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:
     ++# '~/.zsh/' directory as '~/.zsh/_git' and then add the following to your
     ++# ~/.zshrc file:
       #
       #  fpath=(~/.zsh $fpath)
       

-- 
gitgitgadget

[PATCH v3 1/1] doc: Change zsh git completion file name

[Maxim Belsky via GitGitGadget]

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.

Helped-by: Johannes Schindelin <Johannes.Schindelin@gmx.de>
Helped-by: Junio C Hamano <gitster@pobox.com>
Helped-by: SZEDER Gábor <szeder.dev@gmail.com>
Signed-off-by: Maxim Belsky <public.belsky@gmail.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..b480e3f316 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' and then add the following to your
+# ~/.zshrc file:
 #
 #  fpath=(~/.zsh $fpath)
 
-- 
gitgitgadget

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

[Junio C Hamano]

"Maxim Belsky via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Maxim Belsky <public.belsky@gmail.com>
> Subject: Re: [PATCH v3 1/1] doc: Change zsh git completion file name

Lack of attention to the detail.  This is not about changing the
filename anymore.

    Subject: [PATCH v3] completion: clarify installation instruction for zsh

perhaps.  I'll make the change locally, so unless there are other
changes you want to make, there is no need to resend.

Thanks.

> 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.
>
> Helped-by: Johannes Schindelin <Johannes.Schindelin@gmx.de>
> Helped-by: Junio C Hamano <gitster@pobox.com>
> Helped-by: SZEDER Gábor <szeder.dev@gmail.com>
> Signed-off-by: Maxim Belsky <public.belsky@gmail.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..b480e3f316 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' and then add the following to your
> +# ~/.zshrc file:
>  #
>  #  fpath=(~/.zsh $fpath)

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

[Felipe Contreras]

On Tue, Oct 15, 2019 at 3:22 AM SZEDER Gábor <szeder.dev@gmail.com> wrote:

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

It is a requirement. If the file is not named '_git' it will never be
autoloaded. The whole point of naming it that way is that it's loaded
after typing 'git<tab>'.

-- 
Felipe Contreras