[PATCH] docs: improve discoverability of exclude pathspec

[Manav Rathi <mnvrth@gmail.com>]

The ability to exclude paths in pathspecs is not mentioned in the man
pages of git grep and other commands where it might be useful.

Add a pointer to the pathspec syntax and a quick example in the git
grep man page 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.
- Perform general touch ups of surrounding lines.

Signed-off-by: Manav Rathi <mnvrth@gmail.com>
---
 Documentation/git-add.txt          | 27 ++++++++++++++++-----------
 Documentation/git-grep.txt         |  6 ++++++
 Documentation/git-status.txt       |  2 ++
 Documentation/glossary-content.txt |  2 +-
 t/t6132-pathspec-exclude.sh        | 13 ++++++++++++-
 5 files changed, 37 insertions(+), 13 deletions(-)

diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
index f4169fb..6f76f39 100644
--- a/Documentation/git-add.txt
+++ b/Documentation/git-add.txt
@@ -50,17 +50,22 @@ commit.
 OPTIONS
 -------
 <pathspec>...::
- Files to add content from.  Fileglobs (e.g. `*.c`) can
- be given to add all matching files.  Also a
- leading directory name (e.g. `dir` to add `dir/file1`
- and `dir/file2`) can be given to update the index to
- match the current state of the directory as a whole (e.g.
- specifying `dir` will record not just a file `dir/file1`
- modified in the working tree, a file `dir/file2` added to
- the working tree, but also a file `dir/file3` removed from
- 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.
+ Files to add content from.
++
+File globs (e.g. `*.c`) can be given to add all matching files.  A
+leading directory name (e.g. `dir` to add `dir/file1` and `dir/file2`)
+can be given to update the index to match the current state of the
+directory as a whole.
++
+Note that specifying `dir` will record not just a file `dir/file1`
+modified in the working tree, a file `dir/file2` added to the working
+tree, but also a file `dir/file3` removed from the working tree.
+Older versions of Git used to ignore removed files; use the `--no-all`
+option if you want to add new and modified 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 720c785..18b4947 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -289,6 +289,9 @@ providing this option will cause it to die.
 <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
 --------
@@ -305,6 +308,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 d47f198..9f3a78a 100644
--- a/Documentation/git-status.txt
+++ b/Documentation/git-status.txt
@@ -111,6 +111,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 b71b943..6b8888d 100644
--- 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 9dd5cde..7ce91ef 100755
--- 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
-- 
2.10.1