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

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

[Jakub Narebski]

Mention that --pretty=<format> option is used by git-diff-tree only
if both --stdin and -v options are provided.  Because of that it doesn't
make sense to list pretty formats in git-diff-tree(1); linking to
git-show(1) should be enough.

Above changes appear only in git-diff-tree(1) manpage.

Signed-off-by: Jakub Narebski <jnareb@gmail.com>
---
I have stumbled upon this when trying to simplify generating
'commitdiff_plain' view in gitweb.

"make doc" compiles without errors, and produces expected result.

 Documentation/git-diff-tree.txt  |    6 +++++-
 Documentation/pretty-options.txt |    3 +++
 2 files changed, 8 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt
index 58d02c6..afe82e3 100644
--- a/Documentation/git-diff-tree.txt
+++ b/Documentation/git-diff-tree.txt
@@ -24,6 +24,7 @@ Note that "git-diff-tree" can use the tree encapsulated in a commit object.
 
 OPTIONS
 -------
+:git-diff-tree: 1
 include::diff-options.txt[]
 
 <tree-ish>::
@@ -104,7 +105,10 @@ include::pretty-options.txt[]
 	if the diff itself is empty.
 
 
-include::pretty-formats.txt[]
+Pretty Formats
+--------------
+
+For description of pretty formats see for example linkgit:git-show[1]
 
 
 Limiting Output
diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt
index 6d66c74..8c101b9 100644
--- a/Documentation/pretty-options.txt
+++ b/Documentation/pretty-options.txt
@@ -3,6 +3,9 @@
 	Pretty-print the contents of the commit logs in a given format,
 	where '<format>' can be one of 'oneline', 'short', 'medium',
 	'full', 'fuller', 'email', 'raw' and 'format:<string>'.
+ifdef::git-diff-tree[]
+	This option is used for "git-diff-tree --stdin -v" combination.
+endif::git-diff-tree[]
 	When omitted, the format defaults to 'medium'.
 +
 Note: you can specify the default pretty format in the repository
-- 
1.5.5

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

[Junio C Hamano]

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.

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

[Jakub Narebski]

Junio C Hamano wrote:
> 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.

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

Sorry for the/my confusion.

It looks like gitweb's 'commitdiff' and 'commitdiff_plain' views
(actions), both of which can take _two_ commits, needs to be rethough.
Current output doesn't make much sense when the two commits in question
are not parent and child.  Also, simplifying 'commitdiff_plain' by using
git-diff-tree with --pretty=email cannot work with current gitweb's
commitdiff features.

By the way, can one choose one of parents to be shown in ''for the
commit'' mode, or it is only combined (-c, --cc) or all (-m)?
-- 
Jakub Narebski
Poland

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

[Junio C Hamano]

Jakub Narebski <jnareb@gmail.com> writes:

> By the way, can one choose one of parents to be shown in ''for the
> commit'' mode, or it is only combined (-c, --cc) or all (-m)?

Not without using "diff $C^$N $C", no, I do not think so, and that form
will be two-tree case so you won't get a log.

When you treat all parents as equals, there is no good definition of a
single patch for the commit for a merge.