[PATCH] Improve the "diff --git" format documentation

From

AGAndreas Gruenbacher <agruen@suse.de>

Date

Oct 6, 2010, 16:23 UTC

Message-ID

<201010061823.47475.agruen@suse.de>

Hello,

Signed-off-by: Andreas Gruenbacher <agruen@suse.de>
---
 Documentation/diff-generate-patch.txt |   23 ++++++++++++++++++++++-
 1 files changed, 22 insertions(+), 1 deletions(-)

diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-
generate-patch.txt
index 8f9a241..05f2164 100644
--- a/Documentation/diff-generate-patch.txt
+++ b/Documentation/diff-generate-patch.txt
@@ -18,7 +18,8 @@ diff format.
 +
 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 `a/` or `b/` filenames in the
+`diff --git` line.
 +
 When rename/copy is involved, `file1` and `file2` show the
 name of the source file of the rename/copy and the name of
@@ -38,11 +39,31 @@ the file that rename/copy produces, respectively.
        dissimilarity index <number>
        index <hash>..<hash> <mode>
 
+    Path names in extended header lines do not include the `a/` and `b/`
+    prefixes.  The index header includes the <mode> only if the file
+    mode does not change; otherwise, explicit mode headers are included.
+
 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.
 
+    Space characters are not quoted and so when files are copied or
+    renamed, the file names in the "diff --git" line can be
+    ambiguous.
+
+4.  All the `a/` files refer to files before the commit, and all the `b/`
+    files refer to files after the commit; it is incorrect to apply the
+    changes 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
+
 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