Steffen Nurpmeso <steffen@xxxxxxxxxx> writes:
> diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt
> index dbc91f9..8ebeced 100644
> --- a/Documentation/git-ls-tree.txt
> +++ b/Documentation/git-ls-tree.txt
> @@ -33,6 +33,10 @@ in the current working directory. Note that:
> However, the current working directory can be ignored by passing
> --full-tree option.
>
> + - the behaviour is different to that of "/bin/ls" in sofar as non-existing
> + '<path>' arguments are silently ignored and not reflected in the exit
> + status code.
> +
> OPTIONS
> -------
> <tree-ish>::
Sorry, but I did not notice that there was an attached patch when I
was reading your response for the first time. Risk of using an
attachment to e-mail ;-)
I think this issue does not need a separate bullet point. The
existing text says:
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
arguments does not matter.
- the behaviour is similar to that of "/bin/ls" in that the '<path>' 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
'sub/dir' in `HEAD`). You don't want to give a tree that is not at the
root level (e.g. `git ls-tree -r HEAD:sub dir`) in this case, as that
would result in asking for 'sub/sub/dir' in the `HEAD` commit.
However, the current working directory can be ignored by passing
--full-tree option.
and what caused your surprise is already covered by the first bullet
point, if the reader knows what "patterns to match" means in Git's
command line tools; it just needs to be extended to be more
meaningful to those who don't, I think.
How about rewriting the first bullet point like so instead:
- the behaviour is different from that of "/bin/ls" in that the
'<path>' are actually patterns to match, e.g. so specifying
directory name (without `-r`) will behave differently, the order
of the arguments does not matter, and a '<path>' argument that
does not match any path is not an error (i.e. if there is no
path that matches any pattern, nothing is shown in the output).