From: Andreas Gruenbacher <agruen@suse.de>
To: git@vger.kernel.org
Subject: [PATCH] Improve the "diff --git" format documentation
Date: Wed, 6 Oct 2010 18:23:47 +0200 [thread overview]
Message-ID: <201010061823.47475.agruen@suse.de> (raw)
Hello,
here is a small improvement to the documentation of git's extended diff
format. Can this please be included?
Thanks,
Andreas
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
next reply other threads:[~2010-10-06 16:24 UTC|newest]
Thread overview: 10+ messages / expand[flat|nested] mbox.gz Atom feed top
2010-10-06 16:23 Andreas Gruenbacher [this message]
2010-10-06 17:22 ` [PATCH] Improve the "diff --git" format documentation Junio C Hamano
2010-10-06 23:03 ` Andreas Gruenbacher
2010-10-11 13:14 ` Andreas Gruenbacher
2010-10-14 1:55 ` Junio C Hamano
2010-10-14 1:55 ` Junio C Hamano
2010-10-14 10:53 ` Andreas Gruenbacher
2010-10-14 12:39 ` Andreas Gruenbacher
2010-10-14 16:16 ` Jonathan Nieder
2010-10-17 4:43 ` Junio C Hamano
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=201010061823.47475.agruen@suse.de \
--to=agruen@suse.de \
--cc=git@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).