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

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

[Thomas Weißschuh]

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.
+
 Here are the rules regarding the "flags" that you should follow when you are
 scripting Git:
 

base-commit: afa70145a25e81faa685dc0b465e52b45d2444bd
-- 
2.37.2

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

[Junio C Hamano]

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?

 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

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

[Thomas Weißschuh]

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