Steffen Nurpmeso <stef...@sdaoden.eu> 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).

Reply via email to