{"thread":{"id":"46820","subject":"[PATCH] docs: improve discoverability of exclude pathspec","startedAt":"2017-09-24T16:17:32Z","lastAt":"2017-09-25T08:59:19Z","messageCount":4,"participants":["Manav Rathi","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"328773","messageId":"CAEuZsW8vR0LesL=+ZoiFa=BBwhhm=KON+U3H2H9sNdTT+jgBkQ@mail.gmail.com","threadId":"46820","inReplyTo":null,"subject":"[PATCH] docs: improve discoverability of exclude pathspec","fromName":"Manav Rathi","fromEmail":"mnvrth@gmail.com","sentAt":"2017-09-24T16:17:16Z","receivedAt":"2017-09-24T16:17:32Z","isPatch":true,"sender":{"key":"mnvrth@gmail.com","avatar":null},"body":"The ability to exclude paths in pathspecs is not mentioned in the man\npages of git grep and other commands where it might be useful.\n\nAdd a pointer to the pathspec syntax and a quick example in the git\ngrep man page to help the user to discover this ability.\n\nAdd similar pointers from the git-add and git-status man pages.\n\nAdditionally,\n\n- Add a test for the behaviour when multiple exclusions are present.\n- Add a test for the ^ alias.\n- Perform general touch ups of surrounding lines.\n\nSigned-off-by: Manav Rathi <mnvrth@gmail.com>\n---\n Documentation/git-add.txt          | 27 ++++++++++++++++-----------\n Documentation/git-grep.txt         |  6 ++++++\n Documentation/git-status.txt       |  2 ++\n Documentation/glossary-content.txt |  2 +-\n t/t6132-pathspec-exclude.sh        | 13 ++++++++++++-\n 5 files changed, 37 insertions(+), 13 deletions(-)\n\ndiff --git a/Documentation/git-add.txt b/Documentation/git-add.txt\nindex f4169fb..6f76f39 100644\n--- a/Documentation/git-add.txt\n+++ b/Documentation/git-add.txt\n@@ -50,17 +50,22 @@ commit.\n OPTIONS\n -------\n <pathspec>...::\n- Files to add content from.  Fileglobs (e.g. `*.c`) can\n- be given to add all matching files.  Also a\n- leading directory name (e.g. `dir` to add `dir/file1`\n- and `dir/file2`) can be given to update the index to\n- match the current state of the directory as a whole (e.g.\n- specifying `dir` will record not just a file `dir/file1`\n- modified in the working tree, a file `dir/file2` added to\n- the working tree, but also a file `dir/file3` removed from\n- the working tree.  Note that older versions of Git used\n- to ignore removed files; use `--no-all` option if you want\n- to add modified or new files but ignore removed ones.\n+ Files to add content from.\n++\n+File globs (e.g. `*.c`) can be given to add all matching files.  A\n+leading directory name (e.g. `dir` to add `dir/file1` and `dir/file2`)\n+can be given to update the index to match the current state of the\n+directory as a whole.\n++\n+Note that specifying `dir` will record not just a file `dir/file1`\n+modified in the working tree, a file `dir/file2` added to the working\n+tree, but also a file `dir/file3` removed from the working tree.\n+Older versions of Git used to ignore removed files; use the `--no-all`\n+option if you want to add new and modified files but ignore removed\n+ones.\n++\n+For more details about the <pathspec> syntax, see the 'pathspec' entry\n+in linkgit:gitglossary[7].\n\n -n::\n --dry-run::\ndiff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt\nindex 720c785..18b4947 100644\n--- a/Documentation/git-grep.txt\n+++ b/Documentation/git-grep.txt\n@@ -289,6 +289,9 @@ providing this option will cause it to die.\n <pathspec>...::\n  If given, limit the search to paths matching at least one pattern.\n  Both leading paths match and glob(7) patterns are supported.\n++\n+For more details about the <pathspec> syntax, see the 'pathspec' entry\n+in linkgit:gitglossary[7].\n\n Examples\n --------\n@@ -305,6 +308,9 @@ Examples\n  Looks for a line that has `NODE` or `Unexpected` in\n  files that have lines that match both.\n\n+`git grep solution -- :^Documentation`::\n+ Looks for `solution`, excluding files in `Documentation`.\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/git-status.txt b/Documentation/git-status.txt\nindex d47f198..9f3a78a 100644\n--- a/Documentation/git-status.txt\n+++ b/Documentation/git-status.txt\n@@ -111,6 +111,8 @@ configuration variable documented in linkgit:git-config[1].\n  without options are equivalent to 'always' and 'never'\n  respectively.\n\n+<pathspec>...::\n+ See the 'pathspec' entry in linkgit:gitglossary[7].\n\n OUTPUT\n ------\ndiff --git a/Documentation/glossary-content.txt\nb/Documentation/glossary-content.txt\nindex b71b943..6b8888d 100644\n--- a/Documentation/glossary-content.txt\n+++ b/Documentation/glossary-content.txt\n@@ -407,7 +407,7 @@ these forms:\n\n exclude;;\n  After a path matches any non-exclude pathspec, it will be run\n- through all exclude pathspec (magic signature: `!` or its\n+ through all exclude pathspecs (magic signature: `!` or its\n  synonym `^`). If it matches, the path is ignored.  When there\n  is no non-exclude pathspec, the exclusion is applied to the\n  result set as if invoked without any pathspec.\ndiff --git a/t/t6132-pathspec-exclude.sh b/t/t6132-pathspec-exclude.sh\nindex 9dd5cde..7ce91ef 100755\n--- a/t/t6132-pathspec-exclude.sh\n+++ b/t/t6132-pathspec-exclude.sh\n@@ -25,7 +25,7 @@ EOF\n  test_cmp expect actual\n '\n\n-test_expect_success 'exclude only no longer errors out' '\n+test_expect_success 'exclude only pathspec uses default implicit pathspec' '\n  git log --oneline --format=%s -- . \":(exclude)sub\" >expect &&\n  git log --oneline --format=%s -- \":(exclude)sub\" >actual &&\n  test_cmp expect actual\n@@ -183,4 +183,15 @@ EOF\n  test_cmp expect actual\n '\n\n+test_expect_success 'multiple exclusions' '\n+ git ls-files -- :^*/file2 :^sub2 >actual &&\n+ cat <<EOF >expect &&\n+file\n+sub/file\n+sub/sub/file\n+sub/sub/sub/file\n+EOF\n+ test_cmp expect actual\n+'\n+\n test_done\n-- \n2.10.1\n"},{"id":"328779","messageId":"xmqq1smvh9my.fsf@gitster.mtv.corp.google.com","threadId":"46820","inReplyTo":"CAEuZsW8vR0LesL=+ZoiFa=BBwhhm=KON+U3H2H9sNdTT+jgBkQ@mail.gmail.com","subject":"Re: [PATCH] docs: improve discoverability of exclude pathspec","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-09-25T01:03:49Z","receivedAt":"2017-09-25T01:03:56Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Manav Rathi <mnvrth@gmail.com> writes:\n\n> The ability to exclude paths in pathspecs is not mentioned in the man\n> pages of git grep and other commands where it might be useful.\n\nMy reading stutters around \"exclude paths in pathspecs\" in the\nabove.  Perhaps \"exclude paths with a negative pathspec\" instead?\n\n> diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt\n> index f4169fb..6f76f39 100644\n> --- a/Documentation/git-add.txt\n> +++ b/Documentation/git-add.txt\n> @@ -50,17 +50,22 @@ commit.\n>  OPTIONS\n>  -------\n>  <pathspec>...::\n> - Files to add content from.  Fileglobs (e.g. `*.c`) can\n> - be given to add all matching files.  Also a\n> - leading directory name (e.g. `dir` to add `dir/file1`\n> - and `dir/file2`) can be given to update the index to\n> - match the current state of the directory as a whole (e.g.\n> - specifying `dir` will record not just a file `dir/file1`\n> - modified in the working tree, a file `dir/file2` added to\n> - the working tree, but also a file `dir/file3` removed from\n> - the working tree.  Note that older versions of Git used\n> - to ignore removed files; use `--no-all` option if you want\n> - to add modified or new files but ignore removed ones.\n> + Files to add content from.\n> ++\n> +File globs (e.g. `*.c`) can be given to add all matching files.  A\n> +leading directory name (e.g. `dir` to add `dir/file1` and `dir/file2`)\n> +can be given to update the index to match the current state of the\n> +directory as a whole.\n> ++\n> +Note that specifying `dir` will record not just a file `dir/file1`\n> +modified in the working tree, a file `dir/file2` added to the working\n> +tree, but also a file `dir/file3` removed from the working tree.\n> +Older versions of Git used to ignore removed files; use the `--no-all`\n> +option if you want to add new and modified files but ignore removed\n> +ones.\n> ++\n> +For more details about the <pathspec> syntax, see the 'pathspec' entry\n> +in linkgit:gitglossary[7].\n\nThis does a lot more than what the log message claims to do, unlike\nthe changes to other documentation pages.  Splitting the existing\nparagraph in \"git add\" into multiple pagagraphs and changing a few\nwords here and there wasn't part of the bargain.\n\nIt would be easier to judge the merit of the patch if you split it\ninto two steps, if you want all the changes in it.  One would do\nonly what the log message claimed it did, i.e. \"refer to glossary,\ngive an example where appropriate and add test\".  That part I think\neverybody can agree that it is a good change.  The change to the\nintroduction part I am not so sure about.\n\n> -test_expect_success 'exclude only no longer errors out' '\n> +test_expect_success 'exclude only pathspec uses default implicit pathspec' '\n\nThis is a very good change.\n\nBack when the test was written, it was fresh in collective memory\nthat giving only negative pathspec elements without any positive\npathspec element resulted in an error, and that the behaviour was\nupdated so that it would not error out (and it was obvious that\nimplicit positive pattern to be used was to match all), but when\nreading this with fresh eyes, \"no longer errors out\" is much much\nless important than \"start from include all and then subtract paths\nthat match\".\n\n>   git log --oneline --format=%s -- . \":(exclude)sub\" >expect &&\n>   git log --oneline --format=%s -- \":(exclude)sub\" >actual &&\n>   test_cmp expect actual\n> @@ -183,4 +183,15 @@ EOF\n>   test_cmp expect actual\n>  '\n>\n> +test_expect_success 'multiple exclusions' '\n> + git ls-files -- :^*/file2 :^sub2 >actual &&\n\nPlease quote these patterns inside \"pair of dqs\".\n\n> + cat <<EOF >expect &&\n> +file\n> +sub/file\n> +sub/sub/file\n> +sub/sub/sub/file\n> +EOF\n\nBy using <<-\\EOF, you can indent (with tab) the contents of the here\ndocument, like so:\n\n\tcat >expect <<-EOF &&\n\tfile\n\t...\n        EOF\n\nBy the way, please check your e-mail settings.  Your MUA seems to\nhave lost all tabs, and this patch does not apply.\n\nThanks.\n\n> + test_cmp expect actual\n> +'\n> +\n>  test_done\n"},{"id":"328817","messageId":"20170925080900.GA60206@r","threadId":"46820","inReplyTo":"xmqq1smvh9my.fsf@gitster.mtv.corp.google.com","subject":"[PATCHv2] docs: improve discoverability of exclude pathspec","fromName":"Manav Rathi","fromEmail":"mnvrth@gmail.com","sentAt":"2017-09-25T08:09:00Z","receivedAt":"2017-09-25T08:09:17Z","isPatch":false,"sender":{"key":"mnvrth@gmail.com","avatar":null},"body":"\nOn Mon, Sep 25, 2017 at 10:03:49AM +0900, Junio C Hamano wrote:\n> Manav Rathi <mnvrth@gmail.com> writes:\n>\n> > The ability to exclude paths in pathspecs is not mentioned in the man\n> > pages of git grep and other commands where it might be useful.\n> \n> My reading stutters around \"exclude paths in pathspecs\" in the\n> above.  Perhaps \"exclude paths with a negative pathspec\" instead?\n\nChanged\n\n> > diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt\n> \n> This does a lot more than what the log message claims to do, unlike\n> the changes to other documentation pages.  Splitting the existing\n> paragraph in \"git add\" into multiple pagagraphs and changing a few\n> words here and there wasn't part of the bargain.\n> \n> It would be easier to judge the merit of the patch if you split it\n> into two steps, if you want all the changes in it.  One would do\n> only what the log message claimed it did, i.e. \"refer to glossary,\n> give an example where appropriate and add test\".  That part I think\n> everybody can agree that it is a good change.  The change to the\n> introduction part I am not so sure about.\n> \n\nI have undone the auxiliary edits to git-add.txt.\n\n> > -test_expect_success 'exclude only no longer errors out' '\n> > +test_expect_success 'exclude only pathspec uses default implicit pathspec' '\n> \n> This is a very good change.\n> \n\nThank you.\n\n> > +test_expect_success 'multiple exclusions' '\n> > + git ls-files -- :^*/file2 :^sub2 >actual &&\n> \n> Please quote these patterns inside \"pair of dqs\".\n> \n\nDone\n\n> > + cat <<EOF >expect &&\n> > +file\n> > +sub/file\n> > +sub/sub/file\n> > +sub/sub/sub/file\n> > +EOF\n> \n> By using <<-\\EOF, you can indent (with tab) the contents of the here\n> document, like so:\n> \n> \tcat >expect <<-EOF &&\n> \tfile\n> \t...\n>         EOF\n> \n\nDone\n\n> By the way, please check your e-mail settings.  Your MUA seems to\n> have lost all tabs, and this patch does not apply.\n\nI am sorry about that. The instructions in SubmittingPatches clearly\nmentioned that this will happen, but still I was not careful enough.\n\nHopefully this one should not be broken.\n\n-- >8 --\n\nSubject: [PATCH v2] docs: improve discoverability of exclude pathspec\n\nThe ability to exclude paths with a negative pathspec is not mentioned\nin the man pages for git grep and other commands where it might be\nuseful.\n\nAdd an example and a pointer to the pathspec glossary entry in the man\npage for git grep to help the user to discover this ability.\n\nAdd similar pointers from the git-add and git-status man pages.\n\nAdditionally,\n\n- Add a test for the behaviour when multiple exclusions are present.\n- Add a test for the ^ alias.\n- Improve name of existing test.\n- Improve grammar in glossary description of the exclude pathspec.\n\nHelped-by: Junio C Hamano <gitster@pobox.com>\nSigned-off-by: Manav Rathi <mnvrth@gmail.com>\n---\n Documentation/git-add.txt          |  3 +++\n Documentation/git-grep.txt         |  6 ++++++\n Documentation/git-status.txt       |  2 ++\n Documentation/glossary-content.txt |  2 +-\n t/t6132-pathspec-exclude.sh        | 13 ++++++++++++-\n 5 files changed, 24 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-add.txt b/Documentation/git-add.txt\nindex f4169fb..b700bea 100644\n--- a/Documentation/git-add.txt\n+++ b/Documentation/git-add.txt\n@@ -61,6 +61,9 @@ OPTIONS\n \tthe working tree.  Note that older versions of Git used\n \tto ignore removed files; use `--no-all` option if you want\n \tto add modified or new files but ignore removed\tones.\n++\n+For more details about the <pathspec> syntax, see the 'pathspec' entry\n+in linkgit:gitglossary[7].\n \n -n::\n --dry-run::\ndiff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt\nindex 720c785..18b4947 100644\n--- a/Documentation/git-grep.txt\n+++ b/Documentation/git-grep.txt\n@@ -289,6 +289,9 @@ providing this option will cause it to die.\n <pathspec>...::\n \tIf given, limit the search to paths matching at least one pattern.\n \tBoth leading paths match and glob(7) patterns are supported.\n++\n+For more details about the <pathspec> syntax, see the 'pathspec' entry\n+in linkgit:gitglossary[7].\n \n Examples\n --------\n@@ -305,6 +308,9 @@ Examples\n \tLooks for a line that has `NODE` or `Unexpected` in\n \tfiles that have lines that match both.\n \n+`git grep solution -- :^Documentation`::\n+\tLooks for `solution`, excluding files in `Documentation`.\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/git-status.txt b/Documentation/git-status.txt\nindex d47f198..9f3a78a 100644\n--- a/Documentation/git-status.txt\n+++ b/Documentation/git-status.txt\n@@ -111,6 +111,8 @@ configuration variable documented in linkgit:git-config[1].\n \twithout options are equivalent to 'always' and 'never'\n \trespectively.\n \n+<pathspec>...::\n+\tSee the 'pathspec' entry in linkgit:gitglossary[7].\n \n OUTPUT\n ------\ndiff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\nindex b71b943..6b8888d 100644\n--- a/Documentation/glossary-content.txt\n+++ b/Documentation/glossary-content.txt\n@@ -407,7 +407,7 @@ these forms:\n \n exclude;;\n \tAfter a path matches any non-exclude pathspec, it will be run\n-\tthrough all exclude pathspec (magic signature: `!` or its\n+\tthrough all exclude pathspecs (magic signature: `!` or its\n \tsynonym `^`). If it matches, the path is ignored.  When there\n \tis no non-exclude pathspec, the exclusion is applied to the\n \tresult set as if invoked without any pathspec.\ndiff --git a/t/t6132-pathspec-exclude.sh b/t/t6132-pathspec-exclude.sh\nindex 9dd5cde..eb829fc 100755\n--- a/t/t6132-pathspec-exclude.sh\n+++ b/t/t6132-pathspec-exclude.sh\n@@ -25,7 +25,7 @@ EOF\n \ttest_cmp expect actual\n '\n \n-test_expect_success 'exclude only no longer errors out' '\n+test_expect_success 'exclude only pathspec uses default implicit pathspec' '\n \tgit log --oneline --format=%s -- . \":(exclude)sub\" >expect &&\n \tgit log --oneline --format=%s -- \":(exclude)sub\" >actual &&\n \ttest_cmp expect actual\n@@ -183,4 +183,15 @@ EOF\n \ttest_cmp expect actual\n '\n \n+test_expect_success 'multiple exclusions' '\n+\tgit ls-files -- \":^*/file2\" \":^sub2\" >actual &&\n+\tcat <<-\\EOF >expect &&\n+\tfile\n+\tsub/file\n+\tsub/sub/file\n+\tsub/sub/sub/file\n+\tEOF\n+\ttest_cmp expect actual\n+'\n+\n test_done\n-- \n2.10.1\n"},{"id":"328825","messageId":"xmqq377bduht.fsf@gitster.mtv.corp.google.com","threadId":"46820","inReplyTo":"20170925080900.GA60206@r","subject":"Re: [PATCHv2] docs: improve discoverability of exclude pathspec","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-09-25T08:59:10Z","receivedAt":"2017-09-25T08:59:19Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Manav Rathi <mnvrth@gmail.com> writes:\n\n> Hopefully this one should not be broken.\n\nLooks good.\n\nThanks.\n"}]}