From: Junio C Hamano <gitster@pobox.com>
Date: Wed, 21 Sep 2016 20:39:59 GMT
Subject: Re: v2.10.0: ls-tree exit status is always 0, this differs from ls(1)
Message-ID: <xmqqeg4d6l7k.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <20160921194004.QOizfyGm8%steffen@sdaoden.eu>

Steffen Nurpmeso <steffen@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).