Re: [PATCH] Documentation: mention the magic pathspec ":/"
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.
Show 15 quoted lines
> 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(-)
Show changes to diff +7 −3
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 Weißschuh