docs: improve discoverability of exclude pathspec

The ability to exclude paths with a negative pathspec is not mentioned
in the man pages for git grep and other commands where it might be
useful.

Add an example and a pointer to the pathspec glossary entry in the man
page for git grep to help the user to discover this ability.

Add similar pointers from the git-add and git-status man pages.

Additionally,

- Add a test for the behaviour when multiple exclusions are present.
- Add a test for the ^ alias.
- Improve name of existing test.
- Improve grammar in glossary description of the exclude pathspec.

Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Manav Rathi <mnvrth@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
index 7ed63dce0b1f55325497b4fd6879422fe119eaf5..1c3da6d7ddb632b33ce1c4118dec161e816ce7a9 100644 (file)
--- a/Documentation/git-add.txt
+++ b/Documentation/git-add.txt
@@ -61,6 +61,9 @@ OPTIONS
        the working tree.  Note that older versions of Git used
        to ignore removed files; use `--no-all` option if you want
        to add modified or new files but ignore removed ones.
++
+For more details about the <pathspec> syntax, see the 'pathspec' entry
+in linkgit:gitglossary[7].
 
 -n::
 --dry-run::

diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
index 71f32f35089241bc452cfdccdc6b3e9a30f95366..56fb55950af3577a0f0df88fc7dcd62e581b6155 100644 (file)
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -293,6 +293,9 @@ OPTIONS
 <pathspec>...::
        If given, limit the search to paths matching at least one pattern.
        Both leading paths match and glob(7) patterns are supported.
++
+For more details about the <pathspec> syntax, see the 'pathspec' entry
+in linkgit:gitglossary[7].
 
 Examples
 --------
@@ -309,6 +312,9 @@ Examples
        Looks for a line that has `NODE` or `Unexpected` in
        files that have lines that match both.
 
+`git grep solution -- :^Documentation`::
+       Looks for `solution`, excluding files in `Documentation`.
+
 GIT
 ---
 Part of the linkgit:git[1] suite

diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
index d70abc6afe3aa40aaaab2e055ee75d8ee22cdb69..54407112956b9d829b57eeb550e6cd2c63e385d8 100644 (file)
--- a/Documentation/git-status.txt
+++ b/Documentation/git-status.txt
@@ -108,6 +108,8 @@ configuration variable documented in linkgit:git-config[1].
        without options are equivalent to 'always' and 'never'
        respectively.
 
+<pathspec>...::
+       See the 'pathspec' entry in linkgit:gitglossary[7].
 
 OUTPUT
 ------

diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
index 6e991c246915143deba887632def104fc709c9bf..39a6931b9c0e56c1ddc6bef71a4df73cc0606153 100644 (file)
--- a/Documentation/glossary-content.txt
+++ b/Documentation/glossary-content.txt
@@ -407,7 +407,7 @@ these forms:
 
 exclude;;
        After a path matches any non-exclude pathspec, it will be run
-       through all exclude pathspec (magic signature: `!` or its
+       through all exclude pathspecs (magic signature: `!` or its
        synonym `^`). If it matches, the path is ignored.  When there
        is no non-exclude pathspec, the exclusion is applied to the
        result set as if invoked without any pathspec.

diff --git a/t/t6132-pathspec-exclude.sh b/t/t6132-pathspec-exclude.sh
index 9dd5cde5fc53deb365234e815d7142de9a975005..eb829fce97dc7067cbb502b9f5fd2b14c4e74e10 100755 (executable)
--- a/t/t6132-pathspec-exclude.sh
+++ b/t/t6132-pathspec-exclude.sh
@@ -25,7 +25,7 @@ EOF
        test_cmp expect actual
 '
 
-test_expect_success 'exclude only no longer errors out' '
+test_expect_success 'exclude only pathspec uses default implicit pathspec' '
        git log --oneline --format=%s -- . ":(exclude)sub" >expect &&
        git log --oneline --format=%s -- ":(exclude)sub" >actual &&
        test_cmp expect actual
@@ -183,4 +183,15 @@ EOF
        test_cmp expect actual
 '
 
+test_expect_success 'multiple exclusions' '
+       git ls-files -- ":^*/file2" ":^sub2" >actual &&
+       cat <<-\EOF >expect &&
+       file
+       sub/file
+       sub/sub/file
+       sub/sub/sub/file
+       EOF
+       test_cmp expect actual
+'
+
 test_done