Potential Issue with ls-tree documentation

Potential Issue with ls-tree documentation

[Kevin Bowersox]

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.

I'm wondering if this statement is accurate.  Here is my reasoning:

When using this form of the command:

git ls-tree <tree-ish> [<path>]

the <tree-ish> (assuming this is typically a branch name) must be 
specified prior to the path, making the order of the arguments matter 
when issuing the command.

If my reasoning is correct I would be glad to submit the changes for 
review/merge.

Appreciate any insights.

Kevin Bowersox

Re* Potential Issue with ls-tree documentation

[Junio C Hamano]

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

Re: Re* Potential Issue with ls-tree documentation

[Elijah Newren]

On Mon, Jan 13, 2020 at 2:37 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> 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.

This is unreadable, IMO.  I don't understand what it's even trying to say.

>
> 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.

Ah, much better.  But...

>
> 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.

This is much better; but it's still not parseable in my opinion.  Most
of this long sentence is much improved but the phrase "e.g. so
specifying directory name (without `-r`) will behave differently"
still seems quite difficult to understand.  Possible permutations I
run through in my head while trying to read that:

Specifying a directory name behaves differently than specifying a
file?  But only if -r is not specified?  Or is ls-tree output for a
directory different than /bin/ls output for a directory?  But I
thought ls-tree output was different than /bin/ls in all cases, not
just for directories??  Or maybe ls-tree output shows files
differently if one of the pathspecs specified happens to be a
directory, even if the files don't match that directory pathspec?

Being relatively familiar with git and ls-tree, so that I already know
my first five most natural interpretations of that sentence are
incorrect, I think that sentence fragment is trying to say that
ls-trees won't recurse into a specified directory (making it somewhat
like the -d option of ls), but what a convoluted way of saying it.
And I'm still not sure that is what it is actually trying to say.

> - - 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
>
>