Re: [PATCH] Documentation: More on --pretty with git-diff-tree

[Junio C Hamano <gitster@pobox.com>]

Jakub Narebski <jnareb@gmail.com> writes:

> Mention that --pretty=<format> option is used by git-diff-tree only
> if both --stdin and -v options are provided.

Interesting.

    $ git diff-tree --pretty=fuller --stat v1.5.5
    commit 1d2375ddfee18bd3effd2c1f98527cc2f8b1df0a
    Author:     Junio C Hamano <gitster@pobox.com>
    AuthorDate: Mon Apr 7 21:57:43 2008 -0700
    Commit:     Junio C Hamano <gitster@pobox.com>
    CommitDate: Mon Apr 7 21:57:43 2008 -0700

        GIT 1.5.5

        Signed-off-by: Junio C Hamano <gitster@pobox.com>

     Documentation/RelNotes-1.5.5.txt |    8 +-------
     Documentation/git.txt            |    5 +++++
     GIT-VERSION-GEN                  |    2 +-
     3 files changed, 7 insertions(+), 8 deletions(-)

Also:

    $ git rev-parse v1.5.5^0 | git diff-tree --pretty=short --dirstat --stdin
    commit 1d2375ddfee18bd3effd2c1f98527cc2f8b1df0a
    Author: Junio C Hamano <gitster@pobox.com>

        GIT 1.5.5

      89.2% Documentation/

There are two distinct uses for diff-tree, and by understanding it you
would be freed from the confusion.

 * You can compare two arbitrary tree-ish, and because a commit is a
   tree-ish, comparing two commits is a special case of this.  There is no
   reason to expect commit logs to be shown in such a use, and formatting
   options would naturally be ineffective.

 * You can give a commit and ask the command to give difference ``for the
   commit'', in other words, the diff between its parent and the given
   commit.  --stdin is a special case to drive this mechanism repeatedly,
   one commit at a time.  This is showing the diff as one of the
   characteristic of the commit, and allowing to show other attributes of
   the commit such as its message and timestamp makes sense, so formatting
   options take effect.

   As you can see from the above two examples, -v does not have much to do
   with this.