From: Andreas Gruenbacher <agruen@suse.de>
To: Junio C Hamano <gitster@pobox.com>
Cc: git@vger.kernel.org
Subject: Re: [PATCH] Improve the "diff --git" format documentation
Date: Thu, 14 Oct 2010 12:53:11 +0200 [thread overview]
Message-ID: <201010141253.11640.agruen@suse.de> (raw)
In-Reply-To: <7v8w21fsgr.fsf@alter.siamese.dyndns.org>
On Thursday 14 October 2010 03:55:48 Junio C Hamano wrote:
> [some more objections]
Okay, here are the changes we seem to be able to agree on. Let's address the
rest separately.
Andreas
--
[PATCH] 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>
---
Documentation/diff-generate-patch.txt | 40 ++++++++++++++++++++++++--------
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
next prev parent reply other threads:[~2010-10-14 10:53 UTC|newest]
Thread overview: 10+ messages / expand[flat|nested] mbox.gz Atom feed top
2010-10-06 16:23 [PATCH] Improve the "diff --git" format documentation Andreas Gruenbacher
2010-10-06 17:22 ` 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 [this message]
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=201010141253.11640.agruen@suse.de \
--to=agruen@suse.de \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
/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).