doc: add gitpathspecs(7) manual page

Documentation/Makefile

@@ -60,6 +60,7 @@ MAN7_TXT += gitfaq.adoc
 MAN7_TXT += gitglossary.adoc
 MAN7_TXT += gitpacking.adoc
 MAN7_TXT += gitnamespaces.adoc
+MAN7_TXT += gitpathspecs.adoc
 MAN7_TXT += gitremote-helpers.adoc
 MAN7_TXT += gitrevisions.adoc
 MAN7_TXT += gitsubmodules.adoc

Documentation/git-add.adoc

@@ -61,8 +61,7 @@ OPTIONS
 	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].
+For more details about the _<pathspec>_ syntax, see linkgit:gitpathspecs[7].
 
 `-n`::
 `--dry-run`::

Documentation/git-checkout.adoc

@@ -371,7 +371,7 @@ leave out at most one of _<rev-a>_ and _<rev-b>_, in which case it defaults to `
 `<pathspec>...`::
 	Limits the paths affected by the operation.
 +
-For more details, see the 'pathspec' entry in linkgit:gitglossary[7].
+For more details, see linkgit:gitpathspecs[7].
 
 DETACHED HEAD
 -------------

Documentation/git-commit.adoc

@@ -409,7 +409,7 @@ changes to tracked files.
 	already added to the index. The contents of these files are also
 	staged for the next commit on top of what have been staged before.
 +
-For more details, see the 'pathspec' entry in linkgit:gitglossary[7].
+For more details, see linkgit:gitpathspecs[7].
 
 EXAMPLES
 --------

Documentation/git-grep.adoc

@@ -54,8 +54,8 @@ OPTIONS
 	or by ignoring that the current directory is managed by Git.  This
 	is rather similar to running the regular `grep(1)` utility with its
 	`-r` option specified, but with some additional benefits, such as
-	using pathspec patterns to limit paths;  see the 'pathspec' entry
-	in linkgit:gitglossary[7] for more information.
+	using pathspec patterns to limit paths;  see linkgit:gitpathspecs[7]
+	for more information.
 +
 This option cannot be used together with `--cached` or `--untracked`.
 See also `grep.fallbackToNoIndex` in 'CONFIGURATION' below.
@@ -316,8 +316,7 @@ question doesn't support them.
 	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].
+For more details about the <pathspec> syntax, see linkgit:gitpathspecs[7].
 
 EXAMPLES
 --------

Documentation/git-last-modified.adoc

@@ -53,7 +53,7 @@ OPTIONS
 `[--] <pathspec>...`::
 	Show the commit that last modified each path matching _<pathspec>_.
 	If no _<pathspec>_ is given, all files and subdirectories are included.
-	See linkgit:gitglossary[7] for details on pathspec syntax.
+	See linkgit:gitpathspecs[7] for details on pathspec syntax.
 
 OUTPUT
 ------

Documentation/git-reset.adoc

@@ -137,7 +137,7 @@ include::diff-context-options.adoc[]
 `<pathspec>...`::
 	Limits the paths affected by the operation.
 +
-For more details, see the 'pathspec' entry in linkgit:gitglossary[7].
+For more details, see linkgit:gitpathspecs[7].
 
 EXAMPLES
 --------

Documentation/git-restore.adoc

@@ -145,7 +145,7 @@ in linkgit:git-checkout[1] for details.
 `<pathspec>...`::
 	Limits the paths affected by the operation.
 +
-For more details, see the 'pathspec' entry in linkgit:gitglossary[7].
+For more details, see linkgit:gitpathspecs[7].
 
 EXAMPLES
 --------

Documentation/git-rm.adoc

@@ -43,7 +43,7 @@ directories `d` and `d2`, there is a difference between using
 `git rm 'd*'` and `git rm 'd/*'`, as the former will also remove all
 of directory `d2`.
 +
-For more details, see the _<pathspec>_ entry in linkgit:gitglossary[7].
+For more details, see linkgit:gitpathspecs[7].
 
 `-f`::
 `--force`::

Documentation/git-stash.adoc

@@ -279,7 +279,7 @@ that match the pathspec.  The index entries and working tree files
 are then rolled back to the state in HEAD only for these files,
 too, leaving files that do not match the pathspec intact.
 +
-For more details, see the 'pathspec' entry in linkgit:gitglossary[7].
+For more details, see linkgit:gitpathspecs[7].
 
 _<stash>_::
 	This option is only valid for `apply`, `branch`, `drop`, `pop`,

Documentation/git-status.adoc

@@ -155,7 +155,7 @@ ignored, then the directory is not shown, but all contents are shown.
 	See also linkgit:git-diff[1] `--find-renames`.
 
 `<pathspec>...`::
-	See the 'pathspec' entry in linkgit:gitglossary[7].
+	See linkgit:gitpathspecs[7].
 
 OUTPUT
 ------

Documentation/gitpathspecs.adoc

@@ -0,0 +1,32 @@
+gitpathspecs(7)
+===============
+
+NAME
+----
+gitpathspecs - Specifying path selection for Git
+
+SYNOPSIS
+--------
+gitpathspecs
+
+DESCRIPTION
+-----------
+
+Many Git commands accept pathspec arguments to limit the scope of
+operations to a subset of the tree or working tree.
+
+include::pathspecs.adoc[]
+
+SEE ALSO
+--------
+linkgit:git-add[1],
+linkgit:git-grep[1],
+linkgit:git-diff[1],
+linkgit:git-checkout[1],
+linkgit:git-reset[1],
+linkgit:git-ls-files[1],
+linkgit:gitglossary[7]
+
+GIT
+---
+Part of the linkgit:git[1] suite

Documentation/glossary-content.adoc

@@ -353,118 +353,7 @@ Pathspecs are used on the command line of "git ls-files", "git
 ls-tree", "git add", "git grep", "git diff", "git checkout",
 and many other commands to
 limit the scope of operations to some subset of the tree or
-working tree.  See the documentation of each command for whether
-paths are relative to the current directory or toplevel.  The
-pathspec syntax is as follows:
-+
---
-
-* any path matches itself
-* the pathspec up to the last slash represents a
-  directory prefix.  The scope of that pathspec is
-  limited to that subtree.
-* the rest of the pathspec is a pattern for the remainder
-  of the pathname.  Paths relative to the directory
-  prefix will be matched against that pattern using fnmatch(3);
-  in particular, '*' and '?' _can_ match directory separators.
-
---
-+
-For example, Documentation/*.jpg will match all .jpg files
-in the Documentation subtree,
-including Documentation/chapter_1/figure_1.jpg.
-+
-A pathspec that begins with a colon `:` has special meaning.  In the
-short form, the leading colon `:` is followed by zero or more "magic
-signature" letters (which optionally is terminated by another colon `:`),
-and the remainder is the pattern to match against the path.
-The "magic signature" consists of ASCII symbols that are neither
-alphanumeric, glob, regex special characters nor colon.
-The optional colon that terminates the "magic signature" can be
-omitted if the pattern begins with a character that does not belong to
-"magic signature" symbol set and is not a colon.
-+
-In the long form, the leading colon `:` is followed by an open
-parenthesis `(`, a comma-separated list of zero or more "magic words",
-and a close parentheses `)`, and the remainder is the pattern to match
-against the path.
-+
-A pathspec with only a colon means "there is no pathspec". This form
-should not be combined with other pathspec.
-+
---
-top;;
-	The magic word `top` (magic signature: `/`) makes the pattern
-	match from the root of the working tree, even when you are
-	running the command from inside a subdirectory.
-
-literal;;
-	Wildcards in the pattern such as `*` or `?` are treated
-	as literal characters.
-
-icase;;
-	Case insensitive match.
-
-glob;;
-	Git treats the pattern as a shell glob suitable for
-	consumption by fnmatch(3) with the FNM_PATHNAME flag:
-	wildcards in the pattern will not match a / in the pathname.
-	For example, "Documentation/{asterisk}.html" matches
-	"Documentation/git.html" but not "Documentation/ppc/ppc.html"
-	or "tools/perf/Documentation/perf.html".
-+
-Two consecutive asterisks ("`**`") in patterns matched against
-full pathname may have special meaning:
-
- - A leading "`**`" followed by a slash means match in all
-   directories. For example, "`**/foo`" matches file or directory
-   "`foo`" anywhere. "`**/foo/bar`" matches file or directory "`bar`"
-   anywhere that is directly under directory "`foo`".
-
- - A trailing "`/**`" matches everything inside. For example,
-   "`abc/**`" matches all files inside directory "abc", relative
-   to the location of the `.gitignore` file, with infinite depth.
-
- - A slash followed by two consecutive asterisks then a slash
-   matches zero or more directories. For example, "`a/**/b`"
-   matches "`a/b`", "`a/x/b`", "`a/x/y/b`" and so on.
-
- - Other consecutive asterisks are considered invalid.
-
-+
-Glob magic is incompatible with literal magic.
-
-attr;;
-After `attr:` comes a space separated list of "attribute
-requirements", all of which must be met in order for the
-path to be considered a match; this is in addition to the
-usual non-magic pathspec pattern matching.
-See linkgit:gitattributes[5].
-+
-Each of the attribute requirements for the path takes one of
-these forms:
-
-- "`ATTR`" requires that the attribute `ATTR` be set.
-
-- "`-ATTR`" requires that the attribute `ATTR` be unset.
-
-- "`ATTR=VALUE`" requires that the attribute `ATTR` be
-  set to the string `VALUE`.
-
-- "`!ATTR`" requires that the attribute `ATTR` be
-  unspecified.
-
-+
-Note that when matching against a tree object, attributes are still
-obtained from working tree, not from the given tree object.
-
-exclude;;
-	After a path matches any non-exclude pathspec, it will be run
-	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.
---
+working tree.  See linkgit:gitpathspecs[7] for details.
 
 [[def_parent]]parent::
 	A <<def_commit_object,commit object>> contains a (possibly empty) list

Documentation/meson.build

@@ -201,6 +201,7 @@ manpages = {
   'gitglossary.adoc' : 7,
   'gitpacking.adoc' : 7,
   'gitnamespaces.adoc' : 7,
+  'gitpathspecs.adoc' : 7,
   'gitremote-helpers.adoc' : 7,
   'gitrevisions.adoc' : 7,
   'gitsubmodules.adoc' : 7,

Documentation/pathspecs.adoc

@@ -0,0 +1,113 @@
+SPECIFYING PATHSPECS
+--------------------
+
+Pathspecs are used on the command line of "git ls-files", "git
+ls-tree", "git add", "git grep", "git diff", "git checkout",
+and many other commands to
+limit the scope of operations to some subset of the tree or
+working tree.  See the documentation of each command for whether
+paths are relative to the current directory or toplevel.  The
+pathspec syntax is as follows:
+
+* any path matches itself
+* the pathspec up to the last slash represents a
+  directory prefix.  The scope of that pathspec is
+  limited to that subtree.
+* the rest of the pathspec is a pattern for the remainder
+  of the pathname.  Paths relative to the directory
+  prefix will be matched against that pattern using fnmatch(3);
+  in particular, '*' and '?' _can_ match directory separators.
+
+For example, Documentation/*.jpg will match all .jpg files
+in the Documentation subtree,
+including Documentation/chapter_1/figure_1.jpg.
+
+A pathspec that begins with a colon `:` has special meaning.  In the
+short form, the leading colon `:` is followed by zero or more "magic
+signature" letters (which optionally is terminated by another colon `:`),
+and the remainder is the pattern to match against the path.
+The "magic signature" consists of ASCII symbols that are neither
+alphanumeric, glob, regex special characters nor colon.
+The optional colon that terminates the "magic signature" can be
+omitted if the pattern begins with a character that does not belong to
+"magic signature" symbol set and is not a colon.
+
+In the long form, the leading colon `:` is followed by an open
+parenthesis `(`, a comma-separated list of zero or more "magic words",
+and a close parentheses `)`, and the remainder is the pattern to match
+against the path.
+
+A pathspec with only a colon means "there is no pathspec". This form
+should not be combined with other pathspec.
+
+top;;
+	The magic word `top` (magic signature: `/`) makes the pattern
+	match from the root of the working tree, even when you are
+	running the command from inside a subdirectory.
+
+literal;;
+	Wildcards in the pattern such as `*` or `?` are treated
+	as literal characters.
+
+icase;;
+	Case insensitive match.
+
+glob;;
+	Git treats the pattern as a shell glob suitable for
+	consumption by fnmatch(3) with the FNM_PATHNAME flag:
+	wildcards in the pattern will not match a / in the pathname.
+	For example, "Documentation/{asterisk}.html" matches
+	"Documentation/git.html" but not "Documentation/ppc/ppc.html"
+	or "tools/perf/Documentation/perf.html".
++
+Two consecutive asterisks ("`**`") in patterns matched against
+full pathname may have special meaning:
+
+ - A leading "`**`" followed by a slash means match in all
+   directories. For example, "`**/foo`" matches file or directory
+   "`foo`" anywhere. "`**/foo/bar`" matches file or directory "`bar`"
+   anywhere that is directly under directory "`foo`".
+
+ - A trailing "`/**`" matches everything inside. For example,
+   "`abc/**`" matches all files inside directory "abc", relative
+   to the location of the `.gitignore` file, with infinite depth.
+
+ - A slash followed by two consecutive asterisks then a slash
+   matches zero or more directories. For example, "`a/**/b`"
+   matches "`a/b`", "`a/x/b`", "`a/x/y/b`" and so on.
+
+ - Other consecutive asterisks are considered invalid.
+
++
+Glob magic is incompatible with literal magic.
+
+attr;;
+After `attr:` comes a space separated list of "attribute
+requirements", all of which must be met in order for the
+path to be considered a match; this is in addition to the
+usual non-magic pathspec pattern matching.
+See linkgit:gitattributes[5].
++
+Each of the attribute requirements for the path takes one of
+these forms:
+
+- "`ATTR`" requires that the attribute `ATTR` be set.
+
+- "`-ATTR`" requires that the attribute `ATTR` be unset.
+
+- "`ATTR=VALUE`" requires that the attribute `ATTR` be
+  set to the string `VALUE`.
+
+- "`!ATTR`" requires that the attribute `ATTR` be
+  unspecified.
+
++
+Note that when matching against a tree object, attributes are still
+obtained from working tree, not from the given tree object.
+
+exclude;;
+	After a path matches any non-exclude pathspec, it will be run
+	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.

command-list.txt

@@ -231,6 +231,7 @@ gitk                                    mainporcelain
 gitmailmap                              userinterfaces
 gitmodules                              userinterfaces
 gitnamespaces                           guide
+gitpathspecs                            userinterfaces
 gitprotocol-capabilities                developerinterfaces
 gitprotocol-common                      developerinterfaces
 gitprotocol-http                        developerinterfaces