[PATCH] improve documentation for some commands that use pathspecs
After being surprised that git-ls-files expands pathspecs, here's a patch
that would have saved me.
---
Documentation/git-ls-files.txt | 9 +++++----
Documentation/git-ls-tree.txt | 8 ++++----
2 files changed, 9 insertions(+), 8 deletions(-)
diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index e26f01f..f7a3039 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -17,7 +17,7 @@ SYNOPSIS
[--exclude-per-directory=<file>]
[--exclude-standard]
[--error-unmatch] [--with-tree=<tree-ish>]
- [--full-name] [--abbrev] [--] [<file>...]
+ [--full-name] [--abbrev] [--] [<pathspec>...]
DESCRIPTION
-----------
@@ -101,7 +101,7 @@ OPTIONS
--with-tree=<tree-ish>::
When using --error-unmatch to expand the user supplied
- <file> (i.e. path pattern) arguments to paths, pretend
+ <pathspec> arguments to paths, pretend
that paths which were removed in the index since the
named <tree-ish> are still present. Using this option
with `-s` or `-u` options does not make any sense.
@@ -150,9 +150,10 @@ a space) at the start of each line:
\--::
Do not interpret any more arguments as options.
-<file>::
+<pathspec>::
Files to show. If no files are given all files which match the other
- specified criteria are shown.
+ specified criteria are shown. (Note that this isn't really raw
+ pathnames, but rather a list of patterns to match.)
Output
------
diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt
index 16e87fd..58e7f64 100644
--- a/Documentation/git-ls-tree.txt
+++ b/Documentation/git-ls-tree.txt
@@ -11,7 +11,7 @@ SYNOPSIS
[verse]
'git ls-tree' [-d] [-r] [-t] [-l] [-z]
[--name-only] [--name-status] [--full-name] [--full-tree] [--abbrev[=<n>]]
- <tree-ish> [<path>...]
+ <tree-ish> [<pathspec>...]
DESCRIPTION
-----------
@@ -19,11 +19,11 @@ Lists the contents of a given tree object, like what "/bin/ls -a" does
in the current working directory. Note that:
- the behaviour is slightly different from that of "/bin/ls" in that the
- '<path>' denotes just a list of patterns to match, e.g. so specifying
+ '<pathspec>' denotes just a list of patterns to match, e.g. so specifying
directory name (without '-r') will behave differently, and order of the
arguments does not matter.
- - the behaviour is similar to that of "/bin/ls" in that the '<path>' is
+ - the behaviour is similar to that of "/bin/ls" in that the '<pathspec>' is
taken as relative to the current working directory. E.g. when you are
in a directory 'sub' that has a directory 'dir', you can run 'git
ls-tree -r HEAD dir' to list the contents of the tree (that is
@@ -72,7 +72,7 @@ OPTIONS
Do not limit the listing to the current working directory.
Implies --full-name.
-[<path>...]::
+[<pathspec>...]::
When paths are given, show them (note that this isn't really raw
pathnames, but rather a list of patterns to match). Otherwise
implicitly uses the root level of the tree as the sole path argument.
--
2.1.4
Joey Hess <joeyh@joeyh.name>