Re: Re* Potential Issue with ls-tree documentation

[Elijah Newren <newren@gmail.com>]

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