Re* Potential Issue with ls-tree documentation

[Junio C Hamano <gitster@pobox.com>]

Kevin Bowersox <kevin.m.bowersox@gmail.com> writes:

> Within the ls-tree documentation for Git found here:
> https://git-scm.com/docs/git-ls-tree
> <https://git-scm.com/docs/git-ls-tree>
>
> It mentions the following:
>
> 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
> directory name (without |-r|) will behave differently, and order of
> the arguments does not matter.

The above description is solely focused on the pathspec part of the
argument list and the text needs to clarify that.  In other words,
the above paragraph only wants to say:

    Among the paths in the given tree-ish, a subset of paths are
    chosen to be shown by using pathspec, and the way these pathspec
    arguments are used is different from how "/bin/ls" uses its
    arguments.

The "order of the arguments" part is better read as if there is
the word "pathspec" before "arguments" for clarity.  As the synopsis
makes it clear, <tree-ish> must come before the pathspec, so the
order of that part would not be flexible, obviously.

Thanks.

Perhaps something like this?

-- >8 --
Subject: ls-tree doc: clarify and modernize pathspec description

We have been updating our docs to consistently say <pathspec> when
an argument is one and not a path; "ls-tree" takes a tree-ish and
optionally pathspec, so use the correct term.

It is correct that the order of pathspec arguments do not make a
difference in the output unlike the order of path arguments given to
"/bin/ls", but the existing documentation can be misread to allow
having even the <tree-ish> argument at a random place on the command
line, which obviously was not what the original authors intended to
say.  Clarify it.

Noticed-by: Kevin Bowersox <kevin.m.bowersox@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-ls-tree.txt | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)

diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt
index a7515714da..aa368a8d14 100644
--- a/Documentation/git-ls-tree.txt
+++ b/Documentation/git-ls-tree.txt
@@ -11,19 +11,20 @@ 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
 -----------
 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
-   directory name (without `-r`) will behave differently, and order of the
+ - The way <pathspec> is used is slightly different from how "/bin/ls" uses
+   its paths arguments, in that '<pathspec>' denotes just a list of
+   patterns to match, e.g. so specifying directory name (without
+   `-r`) will behave differently, and the order of the pathspec
    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
@@ -73,10 +74,8 @@ OPTIONS
 	Do not limit the listing to the current working directory.
 	Implies --full-name.
 
-[<path>...]::
-	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.
+[<pathspec>...]::
+	When pathspec is given, only show paths that match the pattern.
 
 
 Output Format