Clarify and extend the "git diff" format documentation
Move the similarity and dissimilarity index header description closer to where those extended headers are described. Describe and/or clarify the format used for file modes, pathnames, and the index header. Document that all "old" files refer to the state before applying the *entire* output, and all "new" files refer to the state thereafter. Signed-off-by: Andreas Gruenbacher <agruen@suse.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Andreas Gruenbacher committed
Oct 14, 2010 at 12:53 UTC
9659df52822a2fd7f85725d2ff680871b1f3bdc7
1 file changed
+30
-10
Documentation/diff-generate-patch.txt
+30
-10
@@ -9,16 +9,15 @@ patch file. You can customize the creation of such patches via the
9
GIT_EXTERNAL_DIFF and the GIT_DIFF_OPTS environment variables.
10
11
What the -p option produces is slightly different from the traditional
12
-diff format.
12
+diff format:
13
14
-1. It is preceded with a "git diff" header, that looks like
15
- this:
14
+1. It is preceded with a "git diff" header that looks like this:
15
16
diff --git a/file1 b/file2
17
+
18
The `a/` and `b/` filenames are the same unless rename/copy is
19
involved. Especially, even for a creation or a deletion,
21
-`/dev/null` is _not_ used in place of `a/` or `b/` filenames.
20
+`/dev/null` is _not_ used in place of the `a/` or `b/` filenames.
21
+
22
When rename/copy is involved, `file1` and `file2` show the
23
name of the source file of the rename/copy and the name of
@@ -37,18 +36,39 @@ the file that rename/copy produces, respectively.
36
similarity index <number>
37
dissimilarity index <number>
38
index <hash>..<hash> <mode>
40
-
41
-3. TAB, LF, double quote and backslash characters in pathnames
42
- are represented as `\t`, `\n`, `\"` and `\\`, respectively.
43
- If there is need for such substitution then the whole
44
- pathname is put in double quotes.
45
-
39
++
40
+File modes are printed as 6-digit octal numbers including the file type
41
+and file permission bits.
42
++
43
+Path names in extended headers do not include the `a/` and `b/` prefixes.
44
++
45
The similarity index is the percentage of unchanged lines, and
46
the dissimilarity index is the percentage of changed lines. It
47
is a rounded down integer, followed by a percent sign. The
48
similarity index value of 100% is thus reserved for two equal
49
files, while 100% dissimilarity means that no line from the old
50
file made it into the new one.
51
++
52
+The index line includes the SHA-1 checksum before and after the change.
53
+The <mode> is included if the file mode does not change; otherwise,
54
+separate lines indicate the old and the new mode.
55
+
56
+3. TAB, LF, double quote and backslash characters in pathnames
57
+ are represented as `\t`, `\n`, `\"` and `\\`, respectively.
58
+ If there is need for such substitution then the whole
59
+ pathname is put in double quotes.
60
+
61
+4. All the `file1` files in the output refer to files before the
62
+ commit, and all the `file2` files refer to files after the commit.
63
+ It is incorrect to apply each change to each file sequentially. For
64
+ example, this patch will swap a and b:
65
+
66
+ diff --git a/a b/b
67
+ rename from a
68
+ rename to b
69
+ diff --git a/b b/a
70
+ rename from b
71
+ rename to a
72
73
74
combined diff format