Re: [PATCH] Documentation: mention the magic pathspec ":/"

["Thomas Weißschuh" <thomas@t-8ch.de>]

Hi Junio,

On 2022-08-14 22:12-0700, Junio C Hamano wrote:
> Thomas Weißschuh <thomas@t-8ch.de> writes:
> 
> Here before your sign-off is the place for you to justify why this
> patch is a good idea.
> 
> > Signed-off-by: Thomas Weißschuh <thomas@t-8ch.de>
> > ---
> >  Documentation/gitcli.txt | 2 ++
> >  1 file changed, 2 insertions(+)
> >
> > diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt
> > index 1819a5a185..a421855bdb 100644
> > --- a/Documentation/gitcli.txt
> > +++ b/Documentation/gitcli.txt
> > @@ -78,6 +78,8 @@ you will.
> >     using a '.' as a repository name in Git (a dot-repository) is a relative
> >     path and means your current repository.
> >  
> > + * The magic pathspec `:/` refers to the root of the working tree.
> > +
> 
> This looks somewhat out of place.  Reading the previous entry, I
> notice it is about the path to a repository, not about path in your
> working tree.  The entry before it is about pathspec, so in a sense,
> what is truly out of place is the "dot is how you refer to the
> current repository".
> 
> I do not quite see why we want to single out ":/", i.e.  the "top"
> pathspec magic applied to an empty string, and not talk about the
> case when it was applied to non-empty string, e.g.  ":/*.c".  If we
> talk about pathspec magic, shouldn't we also talk about "exclude"
> magic, e.g. ":!\*.o", here?
> 
> Besides, the new description is not exactly correct. The "top"
> pathspec magic does not inherently refers to the root.  In
> 
>     $ cd sub/dire/ctory && git grep -e pattern
> 
> we tell "git grep" to look for patterns in the current directory
> and in its subdirectories, and with
> 
>     $ cd sub/dire/ctory && git grep -e pattern :/
> 
> we lift the "current directory and below" limitation and instead
> look for matches everywhere, not limited to the root-level directory.
> We can find a patch from sub/foo.txt that is neither in our current
> directory or at the root-level directory.
> 
> So, I do agree that the users must know more than "Many commands
> allow wildcards in paths" (the entry before the "dot is how you can
> refer to the current repository"), I do not think singling out ":/"
> and refer only to that is a wrong way to go about it for this
> document.  The gitcli manual does not even mention 'pathspec', which
> is the keyword to effectively find many things to learn in the
> glossary ("git help glossary"), and it would be the first thing to
> fix here, I would think.
> 
> So after reading your patch and thinking about it for a few days,
> here is what I think is wrong in the current description, plus its
> fix.
> 
> Thoughts?

This looks good, thanks!

I did not even find the existing documentation in gitglossary(7) and the other
pathspecs.
Originally I got to know about the ":/" pathspec from someones example on a
mailing list. Then I grepped the git source and only found some tests and the
entries in the release notes.
So some literal examples in gitglossary(7) maybe help users to find the correct
documentation.

>  Documentation/gitcli.txt | 10 +++++++---
>  1 file changed, 7 insertions(+), 3 deletions(-)
> 
> diff --git c/Documentation/gitcli.txt w/Documentation/gitcli.txt
> index 1819a5a185..40553fc578 100644
> --- c/Documentation/gitcli.txt
> +++ w/Documentation/gitcli.txt
> @@ -57,9 +57,11 @@ When writing a script that is expected to handle random user-input, it is
>  a good practice to make it explicit which arguments are which by placing
>  disambiguating `--` at appropriate places.
>  
> - * Many commands allow wildcards in paths, but you need to protect
> -   them from getting globbed by the shell.  These two mean different
> -   things:
> + * Many commands take paths to work on as "pathspec".  A pathspec element
> +   can be a literal string, which specifies the named path itself, or it
> +   can be a wildcard pattern, which specifies all paths that match the
> +   pattern.  Wildcards may need to be protected from getting globbed by
> +   the shell.  These two mean different things:
>  +
>  --------------------------------
>  $ git restore *.c
> @@ -73,6 +75,8 @@ the paths in the index that match the pattern to be checked out to your
>  working tree.  After running `git add hello.c; rm hello.c`, you will _not_
>  see `hello.c` in your working tree with the former, but with the latter
>  you will.
> ++
> +To learn more about pathspec, see linkgit:gitglossary[7].
>  
>   * Just as the filesystem '.' (period) refers to the current directory,
>     using a '.' as a repository name in Git (a dot-repository) is a relative

Thomas