Merge branch 'cp/p4'

[git.git] / Documentation / diff-format.txt

diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt
index 378e72f38f37eef50135c3907ccd605652f4fd96..9709c35c98bc678d1f2e339c8e2d4bbcd7e6231f 100644 (file)
--- a/Documentation/diff-format.txt
+++ b/Documentation/diff-format.txt
@@ -1,7 +1,7 @@
-The output format from "git-diff-index", "git-diff-tree" and
-"git-diff-files" are very similar.
+The output format from "git-diff-index", "git-diff-tree",
+"git-diff-files" and "git diff --raw" are very similar.
 
-These commands all compare two sets of things; what is 
+These commands all compare two sets of things; what is
 compared differs:
 
 git-diff-index <tree-ish>::
@@ -59,15 +59,38 @@ 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", "git-diff-files" and "git-diff --raw"
+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
 --------------------------
 
 When "git-diff-index", "git-diff-tree", or "git-diff-files" are run
-with a '-p' option, they do not produce the output described above;
-instead they produce a patch file.  You can customize the creation
-of such patches via the GIT_EXTERNAL_DIFF and the GIT_DIFF_OPTS
-environment variables.
+with a '-p' option, or "git diff" without the '--raw' option, they
+do not produce the output described above; instead they produce a
+patch file.  You can customize the creation of such patches via the
+GIT_EXTERNAL_DIFF and the GIT_DIFF_OPTS environment variables.
 
 What the -p option produces is slightly different from the traditional
 diff format.
@@ -104,12 +127,19 @@ the file that rename/copy produces, respectively.
     If there is need for such substitution then the whole
     pathname is put in double quotes.
 
+The similarity index is the percentage of unchanged lines, and
+the dissimilarity index is the percentage of changed lines.  It
+is a rounded down integer, followed by a percent sign.  The
+similarity index value of 100% is thus reserved for two equal
+files, while 100% dissimilarity means that no line from the old
+file made it into the new one.
+
 
 combined diff format
 --------------------
 
-git-diff-tree and git-diff-files can take '-c' or '--cc' option
-to produce 'combined diff', which looks like this:
+"git-diff-tree", "git-diff-files" and "git-diff" can take '-c' or
+'--cc' option to produce 'combined diff', which looks like this:
 
 ------------
 diff --combined describe.c
@@ -117,28 +147,28 @@ index fabadb8,cc95eb0..4866510
 --- a/describe.c
 +++ b/describe.c
 @@@ -98,20 -98,12 +98,20 @@@
-       return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1;
+       return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1;
   }
-  
+
 - static void describe(char *arg)
  -static void describe(struct commit *cmit, int last_one)
 ++static void describe(char *arg, int last_one)
   {
  +     unsigned char sha1[20];
  +     struct commit *cmit;
-       struct commit_list *list;
-       static int initialized = 0;
-       struct commit_name *n;
-  
+       struct commit_list *list;
+       static int initialized = 0;
+       struct commit_name *n;
+
  +     if (get_sha1(arg, sha1) < 0)
  +             usage(describe_usage);
  +     cmit = lookup_commit_reference(sha1);
  +     if (!cmit)
  +             usage(describe_usage);
  +
-       if (!initialized) {
-               initialized = 1;
-               for_each_ref(get_name);
+       if (!initialized) {
+               initialized = 1;
+               for_each_ref(get_name);
 ------------
 
 1.   It is preceded with a "git diff" header, that looks like
@@ -211,4 +241,3 @@ parents).  When shown by `git diff-files -c`, it compares the
 two unresolved merge parents with the working tree file
 (i.e. file1 is stage 2 aka "our version", file2 is stage 3 aka
 "their version").
-