Hi Junio,
On 2022-08-14 22:12-0700, Junio C Hamano wrote:
> Thomas Weißschuh <thomas@xxxxxxxx> 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@xxxxxxxx>
> > ---
> > 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
