summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAndreas Gruenbacher <agruen@suse.de>2010-10-14 10:53:11 (GMT)
committerJunio C Hamano <gitster@pobox.com>2010-10-19 21:15:30 (GMT)
commit9659df52822a2fd7f85725d2ff680871b1f3bdc7 (patch)
tree4adec9b9d553fa2fde2a78253a868aa63bc036be
parent9fbd8986bb475befb27e0597c2ce0a7ce015334c (diff)
downloadgit-9659df52822a2fd7f85725d2ff680871b1f3bdc7.zip
git-9659df52822a2fd7f85725d2ff680871b1f3bdc7.tar.gz
git-9659df52822a2fd7f85725d2ff680871b1f3bdc7.tar.bz2
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>
-rw-r--r--Documentation/diff-generate-patch.txt40
1 files changed, 30 insertions, 10 deletions
diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt
index 8f9a241..3ac2bea 100644
--- a/Documentation/diff-generate-patch.txt
+++ b/Documentation/diff-generate-patch.txt
@@ -9,16 +9,15 @@ 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.
+diff format:
-1. It is preceded with a "git diff" header, that looks like
- this:
+1. It is preceded with a "git diff" header that looks like this:
diff --git a/file1 b/file2
+
The `a/` and `b/` filenames are the same unless rename/copy is
involved. Especially, even for a creation or a deletion,
-`/dev/null` is _not_ used in place of `a/` or `b/` filenames.
+`/dev/null` is _not_ used in place of the `a/` or `b/` filenames.
+
When rename/copy is involved, `file1` and `file2` show the
name of the source file of the rename/copy and the name of
@@ -37,18 +36,39 @@ the file that rename/copy produces, respectively.
similarity index <number>
dissimilarity index <number>
index <hash>..<hash> <mode>
-
-3. TAB, LF, double quote and backslash characters in pathnames
- are represented as `\t`, `\n`, `\"` and `\\`, respectively.
- If there is need for such substitution then the whole
- pathname is put in double quotes.
-
++
+File modes are printed as 6-digit octal numbers including the file type
+and file permission bits.
++
+Path names in extended headers do not include the `a/` and `b/` prefixes.
++
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.
++
+The index line includes the SHA-1 checksum before and after the change.
+The <mode> is included if the file mode does not change; otherwise,
+separate lines indicate the old and the new mode.
+
+3. TAB, LF, double quote and backslash characters in pathnames
+ are represented as `\t`, `\n`, `\"` and `\\`, respectively.
+ If there is need for such substitution then the whole
+ pathname is put in double quotes.
+
+4. All the `file1` files in the output refer to files before the
+ commit, and all the `file2` files refer to files after the commit.
+ It is incorrect to apply each change to each file sequentially. For
+ example, this patch will swap a and b:
+
+ diff --git a/a b/b
+ rename from a
+ rename to b
+ diff --git a/b b/a
+ rename from b
+ rename to a
combined diff format