[PATCH] diff format documentation: describe raw combined diff format

[PATCH] diff format documentation: describe raw combined diff format

[Jakub Narebski]

Add description of raw combined diff format to diff-formats.txt,
as "diff format for merges" section, before "Generating patches..."
section.

Signed-off-by: Jakub Narebski <jnareb@gmail.com>
---
The description of raw combined diff format is based testing the output,
and on what I remember on discussion regarding raw format: the lack of
"score" number (although it should be fairly easy to add it), and path
only for "dst". See for example:

 $ git diff-tree -M -c --raw c182ec90d824168cfb70494bb920c0a2fb590d98

I need documentation of raw combined diff format to allow gitweb to show
diff with any parent and diff --cc (or diff -c), not just diff with the
first parent for a merge.


SIDENOTE: in man pages generated using asciidoc 7.1.2 the literal
block used for examples lacks vertical whitespace after block. For
example the following asciidoc code

  Example:
  
  ------------------------------------------------
  ::100644 100644 100644 fabadb8... cc95eb0... 4866510... MM	describe.c
  ------------------------------------------------
  
  Note that 'combined diff' lists only files which were modified from
 
renders as (make doc; man Documentation/git-diff-tree.1)

  Example:

  ::100644 100644 100644 fabadb8... cc95eb0... 4866510... MM      describe.c
  Note  that combined diff lists only files which were modified from

Note no space after example.

Similar formatting is used very common in the git documentation.
I'd try to upgrade asciidoc and see if the problem persists.


 Documentation/diff-format.txt |   22 ++++++++++++++++++++++
 1 files changed, 22 insertions(+), 0 deletions(-)

diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt
index 378e72f..e38a1f1 100644
--- a/Documentation/diff-format.txt
+++ b/Documentation/diff-format.txt
@@ -59,6 +59,28 @@ When `-z` option is not used, TAB, LF, and backslash characters
 in pathnames are represented as `\t`, `\n`, and `\\`,
 respectively.
 
+diff format for merges
+----------------------
+
+"git-diff-tree" and "git-diff-files" can take '-c' or '--cc' option
+to generate diff output also for merge commits.  The output differs
+from the format described above in the following way:
+
+. there is a colon for each parent
+. there are more "src" modes and "src" sha1
+. status is concatenated status characters for each parent
+. no optional "score" number
+. single path, only for "dst"
+
+Example:
+
+------------------------------------------------
+::100644 100644 100644 fabadb8... cc95eb0... 4866510... MM	describe.c
+------------------------------------------------
+
+Note that 'combined diff' lists only files which were modified from
+all parents.
+
 
 Generating patches with -p
 --------------------------
-- 
1.5.1.3