{"thread":{"id":"25368","subject":"[PATCH] Improve the \"diff --git\" format documentation","startedAt":"2010-10-06T16:23:47Z","lastAt":"2010-10-17T04:43:27Z","messageCount":10,"participants":["Andreas Gruenbacher","Junio C Hamano","Jonathan Nieder"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"152768","messageId":"201010061823.47475.agruen@suse.de","threadId":"25368","inReplyTo":null,"subject":"[PATCH] Improve the \"diff --git\" format documentation","fromName":"Andreas Gruenbacher","fromEmail":"agruen@suse.de","sentAt":"2010-10-06T16:23:47Z","receivedAt":"2010-10-06T16:23:47Z","isPatch":true,"sender":{"key":"agruen@suse.de","avatar":null},"body":"Hello,\n\nhere is a small improvement to the documentation of git's extended diff\nformat. Can this please be included?\n\nThanks,\nAndreas\n\nSigned-off-by: Andreas Gruenbacher \n---\n Documentation/diff-generate-patch.txt | 23 ++++++++++++++++++++++-\n 1 files changed, 22 insertions(+), 1 deletions(-)\n\ndiff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-\ngenerate-patch.txt\nindex 8f9a241..05f2164 100644\n--- a/Documentation/diff-generate-patch.txt\n+++ b/Documentation/diff-generate-patch.txt\n@@ -18,7 +18,8 @@ diff format.\n +\n The `a/` and `b/` filenames are the same unless rename/copy is\n involved. Especially, even for a creation or a deletion,\n-`/dev/null` is _not_ used in place of `a/` or `b/` filenames.\n+`/dev/null` is _not_ used in place of `a/` or `b/` filenames in the\n+`diff --git` line.\n +\n When rename/copy is involved, `file1` and `file2` show the\n name of the source file of the rename/copy and the name of\n@@ -38,11 +39,31 @@ the file that rename/copy produces, respectively.\n dissimilarity index \n index .. \n \n+ Path names in extended header lines do not include the `a/` and `b/`\n+ prefixes. The index header includes the only if the file\n+ mode does not change; otherwise, explicit mode headers are included.\n+\n 3. TAB, LF, double quote and backslash characters in pathnames\n are represented as `\\t`, `\\n`, `\\\"` and `\\\\`, respectively.\n If there is need for such substitution then the whole\n pathname is put in double quotes.\n \n+ Space characters are not quoted and so when files are copied or\n+ renamed, the file names in the \"diff --git\" line can be\n+ ambiguous.\n+\n+4. All the `a/` files refer to files before the commit, and all the `b/`\n+ files refer to files after the commit; it is incorrect to apply the\n+ changes to each file sequentially. For example, this patch will\n+ swap a and b:\n+\n+ diff --git a/a b/b\n+ rename from a\n+ rename to b\n+ diff --git a/b b/a\n+ rename from b\n+ rename to a\n+\n The similarity index is the percentage of unchanged lines, and\n the dissimilarity index is the percentage of changed lines. It\n is a rounded down integer, followed by a percent sign. The\n"},{"id":"152771","messageId":"7vk4lv44os.fsf@alter.siamese.dyndns.org","threadId":"25368","inReplyTo":"201010061823.47475.agruen@suse.de","subject":"Re: [PATCH] Improve the \"diff --git\" format documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-10-06T17:22:11Z","receivedAt":"2010-10-06T17:22:11Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Andreas Gruenbacher writes:\n\n> Hello,\n>\n> here is a small improvement to the documentation of git's extended diff\n> format. Can this please be included?\n>\n> Thanks,\n> Andreas\n>\n> Signed-off-by: Andreas Gruenbacher \n> ---\n\nI thought you have been here long enough to send a patch with some more\nmeaningful log message than that. Could you objectively describe in what\nway is it an \"improvement\" on the subject line?\n\n> Documentation/diff-generate-patch.txt | 23 ++++++++++++++++++++++-\n> 1 files changed, 22 insertions(+), 1 deletions(-)\n>\n> diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-\n> generate-patch.txt\n> index 8f9a241..05f2164 100644\n> --- a/Documentation/diff-generate-patch.txt\n> +++ b/Documentation/diff-generate-patch.txt\n> @@ -18,7 +18,8 @@ diff format.\n> +\n> The `a/` and `b/` filenames are the same unless rename/copy is\n> involved. Especially, even for a creation or a deletion,\n> -`/dev/null` is _not_ used in place of `a/` or `b/` filenames.\n> +`/dev/null` is _not_ used in place of `a/` or `b/` filenames in the\n> +`diff --git` line.\n\nWith a bit more context, the original reads like this:\n\n What the -p option produces is slightly different from the traditional\n diff format.\n\n 1. It is preceded with a \"git diff\" header, that looks like\n this:\n\n diff --git a/file1 b/file2\n +\n The `a/` and `b/` filenames are the same unless rename/copy is\n involved. Especially, even for a creation or a deletion,\n `/dev/null` is _not_ used in place of `a/` or `b/` filenames.\n\nI think the first sentence makes it clear that this section is about '\"git\ndiff\" header', without repeating it like your patch does.\n\n> @@ -38,11 +39,31 @@ the file that rename/copy produces, respectively.\n> dissimilarity index \n> index .. \n> \n> + Path names in extended header lines do not include the `a/` and `b/`\n> + prefixes. The index header includes the only if the file\n> + mode does not change; otherwise, explicit mode headers are included.\n> +\n\nHave you looked at generated output in man and html formats? I suspect\nthat it needs some asciidoc formatting magic, similar to what we already\nhave for the first section (namely, no indent, but the new block is marked\nas a continuation with a lone plus sign at the beginning, instead of being\nseparated by a blank line).\n\n> 3. TAB, LF, double quote and backslash characters in pathnames\n> are represented as `\\t`, `\\n`, `\\\"` and `\\\\`, respectively.\n> If there is need for such substitution then the whole\n> pathname is put in double quotes.\n> \n> + Space characters are not quoted and so when files are copied or\n> + renamed, the file names in the \"diff --git\" line can be\n> + ambiguous.\n\nWhy do you even need to say that, especially after you made it clear that\nrename information is available in the extended header section in an\nunambiguous form?\n\n> +4. All the `a/` files refer to files before the commit, and all the `b/`\n> + files refer to files after the commit; it is incorrect to apply the\n> + changes to each file sequentially. For example, this patch will\n> + swap a and b:\n> +\n> + diff --git a/a b/b\n> + rename from a\n> + rename to b\n> + diff --git a/b b/a\n> + rename from b\n> + rename to a\n> +\n> The similarity index is the percentage of unchanged lines, and\n> the dissimilarity index is the percentage of changed lines. It\n> is a rounded down integer, followed by a percent sign. The\n\nThe new section is a worthwhile addition; I however think this addition\nmakes the description of the similarity/dissimilarity indices further from\nthe section it relates to (it logically is part of section 2), so perhaps\nit should move 3. down and add 4. while at it.\n\nThanks.\n"},{"id":"152821","messageId":"201010070103.17689.agruen@suse.de","threadId":"25368","inReplyTo":"7vk4lv44os.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Improve the \"diff --git\" format documentation","fromName":"Andreas Gruenbacher","fromEmail":"agruen@suse.de","sentAt":"2010-10-06T23:03:17Z","receivedAt":"2010-10-06T23:03:17Z","isPatch":true,"sender":{"key":"agruen@suse.de","avatar":null},"body":"On Wednesday 06 October 2010 19:22:11 Junio C Hamano wrote:\n> [...] Could you objectively describe in what way is it an \"improvement\" on\n> the subject line?\n\nOkay.\n\n> > Documentation/diff-generate-patch.txt | 23 ++++++++++++++++++++++-\n> > 1 files changed, 22 insertions(+), 1 deletions(-)\n> > \n> > diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-\n> > generate-patch.txt\n> > index 8f9a241..05f2164 100644\n> > --- a/Documentation/diff-generate-patch.txt\n> > +++ b/Documentation/diff-generate-patch.txt\n> > @@ -18,7 +18,8 @@ diff format.\n> > \n> > +\n> > The `a/` and `b/` filenames are the same unless rename/copy is\n> > involved. Especially, even for a creation or a deletion,\n> > \n> > -`/dev/null` is _not_ used in place of `a/` or `b/` filenames.\n> > +`/dev/null` is _not_ used in place of `a/` or `b/` filenames in the\n> > +`diff --git` line.\n> \n> With a bit more context, the original reads like this:\n> \n> What the -p option produces is slightly different from the traditional\n> diff format.\n> \n> 1. It is preceded with a \"git diff\" header, that looks like\n> this:\n> \n> diff --git a/file1 b/file2\n> +\n> The `a/` and `b/` filenames are the same unless rename/copy is\n> involved. Especially, even for a creation or a deletion,\n> `/dev/null` is _not_ used in place of `a/` or `b/` filenames.\n> \n> I think the first sentence makes it clear that this section is about '\"git\n> diff\" header', without repeating it like your patch does.\n\nThe text made me wonder how git handles file names in the unified diff\nheaders, which is not mentioned in this section. Also, the way how /dev/null\nis used in unified diff headers may not be known to some users. I have tried\nto clarify both in the attached version.\n\n> > @@ -38,11 +39,31 @@ the file that rename/copy produces, respectively.\n> > \n> > dissimilarity index \n> > index .. \n> > \n> > + Path names in extended header lines do not include the `a/` and `b/`\n> > + prefixes. The index header includes the only if the file\n> > + mode does not change; otherwise, explicit mode headers are included.\n> > +\n> \n> Have you looked at generated output in man and html formats? I suspect\n> that it needs some asciidoc formatting magic, similar to what we already\n> have for the first section (namely, no indent, but the new block is marked\n> as a continuation with a lone plus sign at the beginning, instead of being\n> separated by a blank line).\n\nFixed, thanks.\n\n> > 3. TAB, LF, double quote and backslash characters in pathnames\n> > \n> > are represented as `\\t`, `\\n`, `\\\"` and `\\\\`, respectively.\n> > If there is need for such substitution then the whole\n> > pathname is put in double quotes.\n> > \n> > + Space characters are not quoted and so when files are copied or\n> > + renamed, the file names in the \"diff --git\" line can be\n> > + ambiguous.\n> \n> Why do you even need to say that, especially after you made it clear that\n> rename information is available in the extended header section in an\n> unambiguous form?\n\nThis fact was *extremely* surprising to me (and I still think it is a\nmistake; spaces should at least be quoted in the \"git diff\" line). \nBut documenting it may at least save others this surprise.\n\nI have tried to reword this; could you please check?\n\n> > +4. All the `a/` files refer to files before the commit, and all the\n> > `b/` + files refer to files after the commit; it is incorrect to\n> > apply the + changes to each file sequentially. For example, this\n> > patch will + swap a and b:\n> > +\n> > + diff --git a/a b/b\n> > + rename from a\n> > + rename to b\n> > + diff --git a/b b/a\n> > + rename from b\n> > + rename to a\n> > +\n> > \n> > The similarity index is the percentage of unchanged lines, and\n> > the dissimilarity index is the percentage of changed lines. It\n> > is a rounded down integer, followed by a percent sign. The\n> \n> The new section is a worthwhile addition; I however think this addition\n> makes the description of the similarity/dissimilarity indices further from\n> the section it relates to (it logically is part of section 2), so perhaps\n> it should move 3. down and add 4. while at it.\n\nDone.\n\nThanks,\nAndreas\n\n--\n\n[PATCH] Clarify and extend the \"git diff\" format documentation\n\nMake it more clear that the unified diff header lines *do* use /dev/null\nfor nonexisting files.\n\nMove the similarity and dissimilarity index header description closer to\nwhere those extended headers are described.\n\nDescribe and/or clarify the format used for file modes, pathnames, and\nthe index header. Make it clear that spaces in pathnames are not\nquoted.\n\nDocument that all \"old\" files refer to the state before applying the\n*entire* output, and all \"new\" files refer to the state thereafter.\n\nSigned-off-by: Andreas Gruenbacher \n---\n Documentation/diff-generate-patch.txt | 44 +++++++++++++++++++++++++-------\n 1 files changed, 34 insertions(+), 10 deletions(-)\n\ndiff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt\nindex 8f9a241..e5beef1 100644\n--- a/Documentation/diff-generate-patch.txt\n+++ b/Documentation/diff-generate-patch.txt\n@@ -9,16 +9,16 @@ patch file. You can customize the creation of such patches via the\n GIT_EXTERNAL_DIFF and the GIT_DIFF_OPTS environment variables.\n \n What the -p option produces is slightly different from the traditional\n-diff format.\n+diff format:\n \n-1. It is preceded with a \"git diff\" header, that looks like\n- this:\n+1. It is preceded with a \"git diff\" header that looks like this:\n \n diff --git a/file1 b/file2\n +\n The `a/` and `b/` filenames are the same unless rename/copy is\n involved. Especially, even for a creation or a deletion,\n-`/dev/null` is _not_ used in place of `a/` or `b/` filenames.\n+`/dev/null` is _not_ used in place of the `a/` or `b/` filenames\n+for nonexisting files (unlike in the unified diff headers).\n +\n When rename/copy is involved, `file1` and `file2` show the\n name of the source file of the rename/copy and the name of\n@@ -37,18 +37,42 @@ the file that rename/copy produces, respectively.\n similarity index \n dissimilarity index \n index .. \n-\n-3. TAB, LF, double quote and backslash characters in pathnames\n- are represented as `\\t`, `\\n`, `\\\"` and `\\\\`, respectively.\n- If there is need for such substitution then the whole\n- pathname is put in double quotes.\n-\n++\n+File modes are printed as 6-digit octal numbers including the file type\n+and file permission bits.\n++\n+Path names in extended headers do not include the `a/` and `b/` prefixes.\n++\n The similarity index is the percentage of unchanged lines, and\n the dissimilarity index is the percentage of changed lines. It\n is a rounded down integer, followed by a percent sign. The\n similarity index value of 100% is thus reserved for two equal\n files, while 100% dissimilarity means that no line from the old\n file made it into the new one.\n++\n+The index line includes the SHA-1 checksum before and after the change.\n+The is included if the file mode does not change; otherwise,\n+separate lines indicate the old and the new mode.\n+\n+3. TAB, LF, double quote and backslash characters in pathnames\n+ are represented as `\\t`, `\\n`, `\\\"` and `\\\\`, respectively.\n+ If there is need for such substitution then the whole\n+ pathname is put in double quotes.\n++\n+Space characters in pathnames are _not_ quoted, neither in the \"git\n+diff\" header nor in extended header lines.\n+\n+4. All the `file1` files in the output refer to files before the\n+ commit, and all the `file2` files refer to files after the commit.\n+ It is incorrect to apply each change to each file sequentially. For\n+ example, this patch will swap a and b:\n+\n+ diff --git a/a b/b\n+ rename from a\n+ rename to b\n+ diff --git a/b b/a\n+ rename from b\n+ rename to a\n \n \n combined diff format\n-- \n1.7.3.1.50.g1e633.dirty\n"},{"id":"153231","messageId":"201010111514.29305.agruen@suse.de","threadId":"25368","inReplyTo":"201010070103.17689.agruen@suse.de","subject":"Re: [PATCH] Improve the \"diff --git\" format documentation","fromName":"Andreas Gruenbacher","fromEmail":"agruen@suse.de","sentAt":"2010-10-11T13:14:29Z","receivedAt":"2010-10-11T13:14:29Z","isPatch":true,"sender":{"key":"agruen@suse.de","avatar":null},"body":"Hello,\n\nwhat's the verdict on my second attempt?\n\nThanks,\nAndreas\n"},{"id":"153480","messageId":"7vfww9fsgz.fsf@alter.siamese.dyndns.org","threadId":"25368","inReplyTo":"201010111514.29305.agruen@suse.de","subject":"Re: [PATCH] Improve the \"diff --git\" format documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-10-14T01:55:40Z","receivedAt":"2010-10-14T01:55:40Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Andreas Gruenbacher writes:\n\n> what's the verdict on my second attempt?\n\nSorry, but I didn't notice the \"second attempt\" that was buried in a\nresponse message.\n"},{"id":"153481","messageId":"7v8w21fsgr.fsf@alter.siamese.dyndns.org","threadId":"25368","inReplyTo":"201010070103.17689.agruen@suse.de","subject":"Re: [PATCH] Improve the \"diff --git\" format documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-10-14T01:55:48Z","receivedAt":"2010-10-14T01:55:48Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Andreas Gruenbacher writes:\n\n> The `a/` and `b/` filenames are the same unless rename/copy is\n> involved. Especially, even for a creation or a deletion,\n> -`/dev/null` is _not_ used in place of `a/` or `b/` filenames.\n> +`/dev/null` is _not_ used in place of the `a/` or `b/` filenames\n> +for nonexisting files (unlike in the unified diff headers).\n\nThe description in the parentheses is wrong, unless you qualify whose\n\"unified diff headers\" you are talking about. For example:\n\n http://www.opengroup.org/onlinepubs/9699919799/utilities/diff.html#tag_20_34_10_07\n\ndoes not mention anything about file creation/deletion events. Perhaps\nyou are referring to cvs or svn output, but I think we can safely drop the\nparenthesized part without losing clarity.\n\n> @@ -37,18 +37,42 @@ the file that rename/copy produces, respectively.\n> similarity index \n> dissimilarity index \n> index .. \n> -\n> -3. TAB, LF, double quote and backslash characters in pathnames\n> - are represented as `\\t`, `\\n`, `\\\"` and `\\\\`, respectively.\n> - If there is need for such substitution then the whole\n> - pathname is put in double quotes.\n> -\n> ++\n> +File modes are printed as 6-digit octal numbers including the file type\n> +and file permission bits.\n> ++\n> +Path names in extended headers do not include the `a/` and `b/` prefixes.\n> ++\n> The similarity index is the percentage of unchanged lines, and\n> the dissimilarity index is the percentage of changed lines. It\n> is a rounded down integer, followed by a percent sign. The\n> similarity index value of 100% is thus reserved for two equal\n> files, while 100% dissimilarity means that no line from the old\n> file made it into the new one.\n> ++\n> +The index line includes the SHA-1 checksum before and after the change.\n> +The is included if the file mode does not change; otherwise,\n> +separate lines indicate the old and the new mode.\n> +\n> +3. TAB, LF, double quote and backslash characters in pathnames\n> + are represented as `\\t`, `\\n`, `\\\"` and `\\\\`, respectively.\n> + If there is need for such substitution then the whole\n> + pathname is put in double quotes.\n> ++\n> +Space characters in pathnames are _not_ quoted, neither in the \"git\n> +diff\" header nor in extended header lines.\n\nI am not sure if there is a particular need to spend an extra paragraph to\nspecial case the SP [*1*]. On the other hand, we quote bytes with\nhigh-bit set in \\octal [*2*], unless core.quotepath is set to false, too,\nwhich should probably be described here.\n\n\n[References]\n\n*1* 28fba29 (Do not quote SP., 2005-10-17)\n*2* http://marc.info/?l=git&m=112927316408690&w=2\n"},{"id":"153512","messageId":"201010141253.11640.agruen@suse.de","threadId":"25368","inReplyTo":"7v8w21fsgr.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Improve the \"diff --git\" format documentation","fromName":"Andreas Gruenbacher","fromEmail":"agruen@suse.de","sentAt":"2010-10-14T10:53:11Z","receivedAt":"2010-10-14T10:53:11Z","isPatch":true,"sender":{"key":"agruen@suse.de","avatar":null},"body":"On Thursday 14 October 2010 03:55:48 Junio C Hamano wrote:\n> [some more objections]\n\nOkay, here are the changes we seem to be able to agree on. Let's address the \nrest separately.\n\nAndreas\n\n--\n\n[PATCH] Clarify and extend the \"git diff\" format documentation\n\nMove the similarity and dissimilarity index header description closer to\nwhere those extended headers are described.\n\nDescribe and/or clarify the format used for file modes, pathnames, and\nthe index header.\n\nDocument that all \"old\" files refer to the state before applying the\n*entire* output, and all \"new\" files refer to the state thereafter.\n\nSigned-off-by: Andreas Gruenbacher \n---\n Documentation/diff-generate-patch.txt | 40 ++++++++++++++++++++++++--------\n 1 files changed, 30 insertions(+), 10 deletions(-)\n\ndiff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-\ngenerate-patch.txt\nindex 8f9a241..3ac2bea 100644\n--- a/Documentation/diff-generate-patch.txt\n+++ b/Documentation/diff-generate-patch.txt\n@@ -9,16 +9,15 @@ patch file. You can customize the creation of such patches \nvia the\n GIT_EXTERNAL_DIFF and the GIT_DIFF_OPTS environment variables.\n \n What the -p option produces is slightly different from the traditional\n-diff format.\n+diff format:\n \n-1. It is preceded with a \"git diff\" header, that looks like\n- this:\n+1. It is preceded with a \"git diff\" header that looks like this:\n \n diff --git a/file1 b/file2\n +\n The `a/` and `b/` filenames are the same unless rename/copy is\n involved. Especially, even for a creation or a deletion,\n-`/dev/null` is _not_ used in place of `a/` or `b/` filenames.\n+`/dev/null` is _not_ used in place of the `a/` or `b/` filenames.\n +\n When rename/copy is involved, `file1` and `file2` show the\n name of the source file of the rename/copy and the name of\n@@ -37,18 +36,39 @@ the file that rename/copy produces, respectively.\n similarity index \n dissimilarity index \n index .. \n-\n-3. TAB, LF, double quote and backslash characters in pathnames\n- are represented as `\\t`, `\\n`, `\\\"` and `\\\\`, respectively.\n- If there is need for such substitution then the whole\n- pathname is put in double quotes.\n-\n++\n+File modes are printed as 6-digit octal numbers including the file type\n+and file permission bits.\n++\n+Path names in extended headers do not include the `a/` and `b/` prefixes.\n++\n The similarity index is the percentage of unchanged lines, and\n the dissimilarity index is the percentage of changed lines. It\n is a rounded down integer, followed by a percent sign. The\n similarity index value of 100% is thus reserved for two equal\n files, while 100% dissimilarity means that no line from the old\n file made it into the new one.\n++\n+The index line includes the SHA-1 checksum before and after the change.\n+The is included if the file mode does not change; otherwise,\n+separate lines indicate the old and the new mode.\n+\n+3. TAB, LF, double quote and backslash characters in pathnames\n+ are represented as `\\t`, `\\n`, `\\\"` and `\\\\`, respectively.\n+ If there is need for such substitution then the whole\n+ pathname is put in double quotes.\n+\n+4. All the `file1` files in the output refer to files before the\n+ commit, and all the `file2` files refer to files after the commit.\n+ It is incorrect to apply each change to each file sequentially. For\n+ example, this patch will swap a and b:\n+\n+ diff --git a/a b/b\n+ rename from a\n+ rename to b\n+ diff --git a/b b/a\n+ rename from b\n+ rename to a\n \n \n combined diff format\n"},{"id":"153514","messageId":"201010141439.43168.agruen@suse.de","threadId":"25368","inReplyTo":"7v8w21fsgr.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Improve the \"diff --git\" format documentation","fromName":"Andreas Gruenbacher","fromEmail":"agruen@suse.de","sentAt":"2010-10-14T12:39:42Z","receivedAt":"2010-10-14T12:39:42Z","isPatch":true,"sender":{"key":"agruen@suse.de","avatar":null},"body":"On Thursday 14 October 2010 03:55:48 Junio C Hamano wrote:\n> Andreas Gruenbacher writes:\n> \n> > The `a/` and `b/` filenames are the same unless rename/copy is\n> > involved. Especially, even for a creation or a deletion,\n> > -`/dev/null` is _not_ used in place of `a/` or `b/` filenames.\n> > +`/dev/null` is _not_ used in place of the `a/` or `b/` filenames\n> > +for nonexisting files (unlike in the unified diff headers).\n> \n> The description in the parentheses is wrong, unless you qualify whose\n> \"unified diff headers\" you are talking about.\n\nI was referring to the unified diff headers that git emits, not any other\nutility's output.\n\nPOSIX does not say anything about nonexisting files, and GNU diff with -rN uses an\nEpoch timestamp instead of /dev/null to distinguish between missing and empty\nfiles:\n\n\thttp://www.gnu.org/software/diffutils/manual/html_node/Creating-and-Removing.html\n\n> For example:\n> \n> http://www.opengroup.org/onlinepubs/9699919799/utilities/diff.html#tag_20_34_10_07\n> \n> does not mention anything about file creation/deletion events.\n\nFine, let's make this clear in the \"combined diff\" format description too\nthen.\n\n> Perhaps you are referring to cvs or svn output, but I think we can safely\n> drop the parenthesized part without losing clarity.\n\nI still believe that the documentation should make it very clear how it\nhandles created and deleted files; it really is not obvious to everyone.\n\nCan you live with the attached patch?\n\nThanks,\nAndreas\n\n--\n\n[PATCH] Clarify how /dev/null is used in diffs\n\nSay where the unified diff header comes in the \"git diff\" format, and\nmake it clear that /dev/null is used there.\n\nIn the description of the \"combined diff\" format, do not claim that\ntraditional unified diffs use /dev/null to signal created or deleted files.\n\nSigned-off-by: Andreas Gruenbacher \n---\n Documentation/diff-generate-patch.txt | 26 ++++++++++++++++++--------\n 1 files changed, 18 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt\nindex 3ac2bea..21c4923 100644\n--- a/Documentation/diff-generate-patch.txt\n+++ b/Documentation/diff-generate-patch.txt\n@@ -53,12 +53,22 @@ The index line includes the SHA-1 checksum before and after the change.\n The is included if the file mode does not change; otherwise,\n separate lines indicate the old and the new mode.\n \n-3. TAB, LF, double quote and backslash characters in pathnames\n+3. It is followed by a 'unified' diff which starts with a two-line\n+ from-file/to-file header:\n+\n+ --- a/file1\n+ +++ b/file2\n++\n+This header is omitted if the contents of `file1` and `file2` are identical.\n+To signal created or deleted files, `/dev/null` is used instead of `a/file1`\n+or `b/file2`.\n+\n+4. TAB, LF, double quote and backslash characters in pathnames\n are represented as `\\t`, `\\n`, `\\\"` and `\\\\`, respectively.\n If there is need for such substitution then the whole\n pathname is put in double quotes.\n \n-4. All the `file1` files in the output refer to files before the\n+5. All the `file1` files in the output refer to files before the\n commit, and all the `file2` files refer to files after the commit.\n It is incorrect to apply each change to each file sequentially. For\n example, this patch will swap a and b:\n@@ -133,14 +143,14 @@ information about detected contents movement (renames and\n copying detection) are designed to work with diff of two\n and are not used by combined diff format.\n \n-3. It is followed by two-line from-file/to-file header\n+3. It is followed by a two-line from-file/to-file header similar to the\n+ traditional 'unified' diff format header:\n \n- --- a/file\n- +++ b/file\n+ --- a/file1\n+ +++ b/file2\n +\n-Similar to two-line header for traditional 'unified' diff\n-format, `/dev/null` is used to signal created or deleted\n-files.\n+To signal created or deleted files, `/dev/null` is used instead of `a/file1`\n+or `b/file2`.\n \n 4. Chunk header format is modified to prevent people from\n accidentally feeding it to `patch -p1`. Combined diff format\n"},{"id":"153518","messageId":"20101014161636.GB16500@burratino","threadId":"25368","inReplyTo":"201010141439.43168.agruen@suse.de","subject":"Re: [PATCH] Improve the \"diff --git\" format documentation","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-10-14T16:16:36Z","receivedAt":"2010-10-14T16:16:36Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Andreas Gruenbacher wrote:\n\n> I still believe that the documentation should make it very clear how it\n> handles created and deleted files;\n\nYes - thanks for doing this.\n\n> --- a/Documentation/diff-generate-patch.txt\n> +++ b/Documentation/diff-generate-patch.txt\n> @@ -53,12 +53,22 @@ The index line includes the SHA-1 checksum before and after the change.\n> The is included if the file mode does not change; otherwise,\n> separate lines indicate the old and the new mode.\n> \n> -3. TAB, LF, double quote and backslash characters in pathnames\n> +3. It is followed by a 'unified' diff which starts with a two-line\n\nSo afterwards the section would say:\n\n\tWhat the -p option produces is slightly different from the traditional\n\tdiff format.\n\n\t1. It is preceded with a \"git diff\" header, that looks like\n\t this:\n\n\t diff --git a/file1 b/file2\n\t[...]\n\n\t2. It is followed by one or more extended header lines:\n\n\t old mode \n\t new mode \n\t[...]\n\n\t3. It is followed by a 'unified' diff which starts with a two-line\n\t[...]\n\nAt some point, the reader starts to wonder what \"it\" is. :) (2)\nalready has this problem, since the extended header lines actually\nprecede the traditional diff rather than following it.\n\nHow about:\n\n\tWhat the -p option produces is slightly different[...]\n\n\t1. It is preceded with a \"git diff\" header[...]\n\t2. Next comes one or more extended header lines[...]\n\t3. The from-file/to-file header that follows uses filenames\n\tof the form a/file1 and b/file2 (where \"a/\" and \"b/\" can be\n\treplaced with some other string or removed depending on\n\toptions used):\n\n\t\t--- a/file1\n\t\t+++ b/file2\n\n\tThis header is omitted if[...]\n\t4. TAB, LF, double quote, and [...]\n\nJonathan\n"},{"id":"153655","messageId":"7vvd515t00.fsf@alter.siamese.dyndns.org","threadId":"25368","inReplyTo":"20101014161636.GB16500@burratino","subject":"Re: [PATCH] Improve the \"diff --git\" format documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-10-17T04:43:27Z","receivedAt":"2010-10-17T04:43:27Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jonathan Nieder writes:\n\n> ...\n> At some point, the reader starts to wonder what \"it\" is. :) (2)\n> already has this problem, since the extended header lines actually\n> precede the traditional diff rather than following it.\n>\n> How about:\n> \n> \tWhat the -p option produces is slightly different[...]\n>\n> \t1. It is preceded with a \"git diff\" header[...]\n> \t2. Next comes one or more extended header lines[...]\n> \t3. The from-file/to-file header that follows uses filenames\n> \tof the form a/file1 and b/file2 (where \"a/\" and \"b/\" can be\n> \treplaced with some other string or removed depending on\n> \toptions used):\n>\n> \t\t--- a/file1\n> \t\t+++ b/file2\n>\n> \tThis header is omitted if[...]\n> \t4. TAB, LF, double quote, and [...]\n\nQuite sensible point to raise, which I completely missed. Thanks.\n"}]}