{"thread":{"id":"58303","subject":"[PATCH] Documentation: mention the magic pathspec \":/\"","startedAt":"2022-08-14T10:03:06Z","lastAt":"2022-08-16T14:09:04Z","messageCount":3,"participants":["Thomas Weißschuh","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"461189","messageId":"20220814095253.3422612-1-thomas@t-8ch.de","threadId":"58303","inReplyTo":null,"subject":"[PATCH] Documentation: mention the magic pathspec \":/\"","fromName":"Thomas Weißschuh","fromEmail":"thomas@t-8ch.de","sentAt":"2022-08-14T09:52:53Z","receivedAt":"2022-08-14T10:03:06Z","isPatch":true,"sender":{"key":"thomas@t-8ch.de","avatar":"https://avatars.githubusercontent.com/u/717901?v=4"},"body":"Signed-off-by: Thomas Weißschuh <thomas@t-8ch.de>\n---\n Documentation/gitcli.txt | 2 ++\n 1 file changed, 2 insertions(+)\n\ndiff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt\nindex 1819a5a185..a421855bdb 100644\n--- a/Documentation/gitcli.txt\n+++ b/Documentation/gitcli.txt\n@@ -78,6 +78,8 @@ you will.\n    using a '.' as a repository name in Git (a dot-repository) is a relative\n    path and means your current repository.\n \n+ * The magic pathspec `:/` refers to the root of the working tree.\n+\n Here are the rules regarding the \"flags\" that you should follow when you are\n scripting Git:\n \n\nbase-commit: afa70145a25e81faa685dc0b465e52b45d2444bd\n-- \n2.37.2\n\n"},{"id":"461214","messageId":"xmqqsfly3xar.fsf@gitster.g","threadId":"58303","inReplyTo":"20220814095253.3422612-1-thomas@t-8ch.de","subject":"Re: [PATCH] Documentation: mention the magic pathspec \":/\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-08-15T05:12:12Z","receivedAt":"2022-08-15T05:12:23Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Thomas Weißschuh <thomas@t-8ch.de> writes:\n\nHere before your sign-off is the place for you to justify why this\npatch is a good idea.\n\n> Signed-off-by: Thomas Weißschuh <thomas@t-8ch.de>\n> ---\n>  Documentation/gitcli.txt | 2 ++\n>  1 file changed, 2 insertions(+)\n>\n> diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt\n> index 1819a5a185..a421855bdb 100644\n> --- a/Documentation/gitcli.txt\n> +++ b/Documentation/gitcli.txt\n> @@ -78,6 +78,8 @@ you will.\n>     using a '.' as a repository name in Git (a dot-repository) is a relative\n>     path and means your current repository.\n>  \n> + * The magic pathspec `:/` refers to the root of the working tree.\n> +\n\nThis looks somewhat out of place.  Reading the previous entry, I\nnotice it is about the path to a repository, not about path in your\nworking tree.  The entry before it is about pathspec, so in a sense,\nwhat is truly out of place is the \"dot is how you refer to the\ncurrent repository\".\n\nI do not quite see why we want to single out \":/\", i.e.  the \"top\"\npathspec magic applied to an empty string, and not talk about the\ncase when it was applied to non-empty string, e.g.  \":/*.c\".  If we\ntalk about pathspec magic, shouldn't we also talk about \"exclude\"\nmagic, e.g. \":!\\*.o\", here?\n\nBesides, the new description is not exactly correct. The \"top\"\npathspec magic does not inherently refers to the root.  In\n\n    $ cd sub/dire/ctory && git grep -e pattern\n\nwe tell \"git grep\" to look for patterns in the current directory\nand in its subdirectories, and with\n\n    $ cd sub/dire/ctory && git grep -e pattern :/\n\nwe lift the \"current directory and below\" limitation and instead\nlook for matches everywhere, not limited to the root-level directory.\nWe can find a patch from sub/foo.txt that is neither in our current\ndirectory or at the root-level directory.\n\nSo, I do agree that the users must know more than \"Many commands\nallow wildcards in paths\" (the entry before the \"dot is how you can\nrefer to the current repository\"), I do not think singling out \":/\"\nand refer only to that is a wrong way to go about it for this\ndocument.  The gitcli manual does not even mention 'pathspec', which\nis the keyword to effectively find many things to learn in the\nglossary (\"git help glossary\"), and it would be the first thing to\nfix here, I would think.\n\nSo after reading your patch and thinking about it for a few days,\nhere is what I think is wrong in the current description, plus its\nfix.\n\nThoughts?\n\n Documentation/gitcli.txt | 10 +++++++---\n 1 file changed, 7 insertions(+), 3 deletions(-)\n\ndiff --git c/Documentation/gitcli.txt w/Documentation/gitcli.txt\nindex 1819a5a185..40553fc578 100644\n--- c/Documentation/gitcli.txt\n+++ w/Documentation/gitcli.txt\n@@ -57,9 +57,11 @@ When writing a script that is expected to handle random user-input, it is\n a good practice to make it explicit which arguments are which by placing\n disambiguating `--` at appropriate places.\n \n- * Many commands allow wildcards in paths, but you need to protect\n-   them from getting globbed by the shell.  These two mean different\n-   things:\n+ * Many commands take paths to work on as \"pathspec\".  A pathspec element\n+   can be a literal string, which specifies the named path itself, or it\n+   can be a wildcard pattern, which specifies all paths that match the\n+   pattern.  Wildcards may need to be protected from getting globbed by\n+   the shell.  These two mean different things:\n +\n --------------------------------\n $ git restore *.c\n@@ -73,6 +75,8 @@ the paths in the index that match the pattern to be checked out to your\n working tree.  After running `git add hello.c; rm hello.c`, you will _not_\n see `hello.c` in your working tree with the former, but with the latter\n you will.\n++\n+To learn more about pathspec, see linkgit:gitglossary[7].\n \n  * Just as the filesystem '.' (period) refers to the current directory,\n    using a '.' as a repository name in Git (a dot-repository) is a relative\n"},{"id":"461283","messageId":"89a2217a-dc62-47e1-96f3-94ee99f2b0d6@t-8ch.de","threadId":"58303","inReplyTo":"xmqqsfly3xar.fsf@gitster.g","subject":"Re: [PATCH] Documentation: mention the magic pathspec \":/\"","fromName":"Thomas Weißschuh","fromEmail":"thomas@t-8ch.de","sentAt":"2022-08-16T14:08:44Z","receivedAt":"2022-08-16T14:09:04Z","isPatch":true,"sender":{"key":"thomas@t-8ch.de","avatar":"https://avatars.githubusercontent.com/u/717901?v=4"},"body":"Hi Junio,\n\nOn 2022-08-14 22:12-0700, Junio C Hamano wrote:\n> Thomas Weißschuh <thomas@t-8ch.de> writes:\n> \n> Here before your sign-off is the place for you to justify why this\n> patch is a good idea.\n> \n> > Signed-off-by: Thomas Weißschuh <thomas@t-8ch.de>\n> > ---\n> >  Documentation/gitcli.txt | 2 ++\n> >  1 file changed, 2 insertions(+)\n> >\n> > diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt\n> > index 1819a5a185..a421855bdb 100644\n> > --- a/Documentation/gitcli.txt\n> > +++ b/Documentation/gitcli.txt\n> > @@ -78,6 +78,8 @@ you will.\n> >     using a '.' as a repository name in Git (a dot-repository) is a relative\n> >     path and means your current repository.\n> >  \n> > + * The magic pathspec `:/` refers to the root of the working tree.\n> > +\n> \n> This looks somewhat out of place.  Reading the previous entry, I\n> notice it is about the path to a repository, not about path in your\n> working tree.  The entry before it is about pathspec, so in a sense,\n> what is truly out of place is the \"dot is how you refer to the\n> current repository\".\n> \n> I do not quite see why we want to single out \":/\", i.e.  the \"top\"\n> pathspec magic applied to an empty string, and not talk about the\n> case when it was applied to non-empty string, e.g.  \":/*.c\".  If we\n> talk about pathspec magic, shouldn't we also talk about \"exclude\"\n> magic, e.g. \":!\\*.o\", here?\n> \n> Besides, the new description is not exactly correct. The \"top\"\n> pathspec magic does not inherently refers to the root.  In\n> \n>     $ cd sub/dire/ctory && git grep -e pattern\n> \n> we tell \"git grep\" to look for patterns in the current directory\n> and in its subdirectories, and with\n> \n>     $ cd sub/dire/ctory && git grep -e pattern :/\n> \n> we lift the \"current directory and below\" limitation and instead\n> look for matches everywhere, not limited to the root-level directory.\n> We can find a patch from sub/foo.txt that is neither in our current\n> directory or at the root-level directory.\n> \n> So, I do agree that the users must know more than \"Many commands\n> allow wildcards in paths\" (the entry before the \"dot is how you can\n> refer to the current repository\"), I do not think singling out \":/\"\n> and refer only to that is a wrong way to go about it for this\n> document.  The gitcli manual does not even mention 'pathspec', which\n> is the keyword to effectively find many things to learn in the\n> glossary (\"git help glossary\"), and it would be the first thing to\n> fix here, I would think.\n> \n> So after reading your patch and thinking about it for a few days,\n> here is what I think is wrong in the current description, plus its\n> fix.\n> \n> Thoughts?\n\nThis looks good, thanks!\n\nI did not even find the existing documentation in gitglossary(7) and the other\npathspecs.\nOriginally I got to know about the \":/\" pathspec from someones example on a\nmailing list. Then I grepped the git source and only found some tests and the\nentries in the release notes.\nSo some literal examples in gitglossary(7) maybe help users to find the correct\ndocumentation.\n\n>  Documentation/gitcli.txt | 10 +++++++---\n>  1 file changed, 7 insertions(+), 3 deletions(-)\n> \n> diff --git c/Documentation/gitcli.txt w/Documentation/gitcli.txt\n> index 1819a5a185..40553fc578 100644\n> --- c/Documentation/gitcli.txt\n> +++ w/Documentation/gitcli.txt\n> @@ -57,9 +57,11 @@ When writing a script that is expected to handle random user-input, it is\n>  a good practice to make it explicit which arguments are which by placing\n>  disambiguating `--` at appropriate places.\n>  \n> - * Many commands allow wildcards in paths, but you need to protect\n> -   them from getting globbed by the shell.  These two mean different\n> -   things:\n> + * Many commands take paths to work on as \"pathspec\".  A pathspec element\n> +   can be a literal string, which specifies the named path itself, or it\n> +   can be a wildcard pattern, which specifies all paths that match the\n> +   pattern.  Wildcards may need to be protected from getting globbed by\n> +   the shell.  These two mean different things:\n>  +\n>  --------------------------------\n>  $ git restore *.c\n> @@ -73,6 +75,8 @@ the paths in the index that match the pattern to be checked out to your\n>  working tree.  After running `git add hello.c; rm hello.c`, you will _not_\n>  see `hello.c` in your working tree with the former, but with the latter\n>  you will.\n> ++\n> +To learn more about pathspec, see linkgit:gitglossary[7].\n>  \n>   * Just as the filesystem '.' (period) refers to the current directory,\n>     using a '.' as a repository name in Git (a dot-repository) is a relative\n\nThomas\n"}]}