{"thread":{"id":"51853","subject":"[PATCH 1/2] diff, log doc: say \"patch text\" instead of \"patches\"","startedAt":"2019-09-15T16:55:36Z","lastAt":"2019-09-17T18:40:23Z","messageCount":6,"participants":["Johannes Sixt","Martin Ågren","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"382395","messageId":"fac55175-dc1e-addf-194b-97aaf6a33e3b@kdbg.org","threadId":"51853","inReplyTo":null,"subject":"[PATCH 1/2] diff, log doc: say \"patch text\" instead of \"patches\"","fromName":"Johannes Sixt","fromEmail":"j6t@kdbg.org","sentAt":"2019-09-15T16:55:30Z","receivedAt":"2019-09-15T16:55:36Z","isPatch":true,"sender":{"key":"j6t@kdbg.org","avatar":"https://avatars.githubusercontent.com/u/14810926?v=4"},"body":"A poster on Stackoverflow was confused that the documentation of git-log\npromised to generate \"patches\" or \"patch files\" with -p, but there were\nnone to be found. Rewrite the corresponding paragraph to talk about\n\"patch text\" to avoid the confusion.\n\nShorten the language to say \"X does Y\" in place of \"X does not Z, but Y\".\n\nCross-reference the referred-to commands like the rest of the file does.\n\nMention porcelain commands before plumbing commands because I guess that\nthe paragraph is read more frequently in their context.\n\nSigned-off-by: Johannes Sixt \n---\n I do not have the toolchain to check that a correct result is produced.\n\n Documentation/diff-generate-patch.txt | 17 +++++++++--------\n 1 file changed, 9 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt\nindex f10ca410ad..c6bbb2ac22 100644\n--- a/Documentation/diff-generate-patch.txt\n+++ b/Documentation/diff-generate-patch.txt\n@@ -1,11 +1,12 @@\n-Generating patches with -p\n---------------------------\n-\n-When \"git-diff-index\", \"git-diff-tree\", or \"git-diff-files\" are run\n-with a `-p` option, \"git diff\" without the `--raw` option, or\n-\"git log\" with the \"-p\" option, they\n-do not produce the output described above; instead they produce a\n-patch file. You can customize the creation of such patches via the\n+Generating patch text with -p\n+-----------------------------\n+\n+Running\n+linkgit:git-diff[1] without the `--raw` option,\n+or linkgit:git-log[1], linkgit:git-diff-index[1], linkgit:git-diff-tree[1],\n+or linkgit:git-diff-files[1] with the `-p` option\n+produces patch text instead of the usual output.\n+You can customize the creation of patch text 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-- \n2.23.0.93.g91d3f15def\n"},{"id":"382396","messageId":"4e9892b1-9d9e-f088-9e56-70f3b02fc9e1@kdbg.org","threadId":"51853","inReplyTo":"fac55175-dc1e-addf-194b-97aaf6a33e3b@kdbg.org","subject":"[PATCH 2/2] diff, log doc: small grammer, format, and language fixes","fromName":"Johannes Sixt","fromEmail":"j6t@kdbg.org","sentAt":"2019-09-15T16:57:48Z","receivedAt":"2019-09-15T16:57:51Z","isPatch":true,"sender":{"key":"j6t@kdbg.org","avatar":"https://avatars.githubusercontent.com/u/14810926?v=4"},"body":"- Replace \"SHA-1\" by \"object name\", the modern name for hashes.\n\n- Correct a few grammar weaknesses.\n\n- Do not accidentally format a phrase in teletype font where quotes are\n intended.\n\nSigned-off-by: Johannes Sixt \n---\n I do not have the toolchain to check that a correct result is produced.\n\n Documentation/diff-generate-patch.txt | 12 ++++++------\n 1 file changed, 6 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt\nindex c6bbb2ac22..ece1a2b66e 100644\n--- a/Documentation/diff-generate-patch.txt\n+++ b/Documentation/diff-generate-patch.txt\n@@ -50,7 +50,7 @@ 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 index line includes the blob object names 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@@ -71,7 +71,7 @@ separate lines indicate the old and the new mode.\n rename to a\n \n \n-combined diff format\n+Combined diff format\n --------------------\n \n Any diff-generating command can take the `-c` or `--cc` option to\n@@ -81,7 +81,7 @@ linkgit:git-show[1]. Note also that you can give the `-m` option to any\n of these commands to force generation of diffs with individual parents\n of a merge.\n \n-A 'combined diff' format looks like this:\n+A \"combined diff\" format looks like this:\n \n ------------\n diff --combined describe.c\n@@ -114,11 +114,11 @@ index fabadb8,cc95eb0..4866510\n ------------\n \n 1. It is preceded with a \"git diff\" header, that looks like\n- this (when `-c` option is used):\n+ this (when the `-c` option is used):\n \n diff --combined file\n +\n-or like this (when `--cc` option is used):\n+or like this (when the `--cc` option is used):\n \n diff --cc file\n \n@@ -161,7 +161,7 @@ parents.\n 4. Chunk header format is modified to prevent people from\n accidentally feeding it to `patch -p1`. Combined diff format\n was created for review of merge commit changes, and was not\n- meant for apply. The change is similar to the change in the\n+ meant to be applied. The change is similar to the change in the\n extended 'index' header:\n \n @@@ @@@\n-- \n2.23.0.93.g91d3f15def\n"},{"id":"382428","messageId":"CAN0heSoaYf0_2FhKQNnswLvFppu=dyBcKGYB_Jd=uF70yjNiCQ@mail.gmail.com","threadId":"51853","inReplyTo":"fac55175-dc1e-addf-194b-97aaf6a33e3b@kdbg.org","subject":"Re: [PATCH 1/2] diff, log doc: say \"patch text\" instead of \"patches\"","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2019-09-16T17:19:44Z","receivedAt":"2019-09-16T17:19:58Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Sun, 15 Sep 2019 at 21:26, Johannes Sixt wrote:\n> I do not have the toolchain to check that a correct result is produced.\n\nBut I do. I've tested this patch and 2/2 with AsciiDoc 8.6.10 and\nAsciidoctor 1.5.5, as well as with Asciidoctor 2.0.10 (on top of brian's\nrecent patch so that it builds to begin with). They all render this\nnicely.\n\nBoth of these patches seem like good changes to me.\n\nMartin\n"},{"id":"382451","messageId":"xmqqv9ts9fox.fsf@gitster-ct.c.googlers.com","threadId":"51853","inReplyTo":"CAN0heSoaYf0_2FhKQNnswLvFppu=dyBcKGYB_Jd=uF70yjNiCQ@mail.gmail.com","subject":"Re: [PATCH 1/2] diff, log doc: say \"patch text\" instead of \"patches\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-09-16T19:58:06Z","receivedAt":"2019-09-16T19:58:12Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Martin Ågren writes:\n\n> On Sun, 15 Sep 2019 at 21:26, Johannes Sixt wrote:\n>> I do not have the toolchain to check that a correct result is produced.\n>\n> But I do. I've tested this patch and 2/2 with AsciiDoc 8.6.10 and\n> Asciidoctor 1.5.5, as well as with Asciidoctor 2.0.10 (on top of brian's\n> recent patch so that it builds to begin with). They all render this\n> nicely.\n>\n> Both of these patches seem like good changes to me.\n\nThanks, both. I am neutral between \"patch\" and \"patch text\", but if\nthe latter is more easily understood by readers, that would be\ngreat. \"patch *file*\" certainly does sound misleading.\n\nI wonder if the result becomes even clearer if we dropped \"instead\nof the usual output\". It is a given that presence of an option\nwould change the behaviour, so \"instead of the usual\" does not add\nany value in the context of the explanation we are giving.\n\nAlso I question the value of the \"running git diff without --raw\noption\" sentence; \"diff --stat\" is also a way to suppress the patch\ntext and see only the overview; I know it is not a new problem this\npatch introduces, but the objective of this patch is clarify about\nthe generation of output in patch format, so...\n"},{"id":"382457","messageId":"76602d23-f2b2-4a15-21ad-7bd91a4b5e44@kdbg.org","threadId":"51853","inReplyTo":"xmqqv9ts9fox.fsf@gitster-ct.c.googlers.com","subject":"[PATCH v2 1/2] diff, log doc: say \"patch text\" instead of \"patches\"","fromName":"Johannes Sixt","fromEmail":"j6t@kdbg.org","sentAt":"2019-09-16T20:46:21Z","receivedAt":"2019-09-16T20:46:25Z","isPatch":true,"sender":{"key":"j6t@kdbg.org","avatar":"https://avatars.githubusercontent.com/u/14810926?v=4"},"body":"Am 16.09.19 um 21:58 schrieb Junio C Hamano:\n> I wonder if the result becomes even clearer if we dropped \"instead\n> of the usual output\". It is a given that presence of an option\n> would change the behaviour, so \"instead of the usual\" does not add\n> any value in the context of the explanation we are giving.\n\nAgreed.\n\n> Also I question the value of the \"running git diff without --raw\n> option\" sentence; \"diff --stat\" is also a way to suppress the patch\n> text and see only the overview; I know it is not a new problem this\n> patch introduces, but the objective of this patch is clarify about\n> the generation of output in patch format, so...\n\nYou have a point here, too.\n\nBelow is v2 of just patch 1/2. 2/2 remains unchanged. I've added\ngit-show to the enumeration.\n\n--- 8< ---\ndiff, log doc: say \"patch text\" instead of \"patches\"\n\nA poster on Stackoverflow was confused that the documentation of git-log\npromised to generate \"patches\" or \"patch files\" with -p, but there were\nnone to be found. Rewrite the corresponding paragraph to talk about\n\"patch text\" to avoid the confusion.\n\nShorten the language to say \"X does Y\" in place of \"X does not Z, but Y\".\n\nCross-reference the referred-to commands like the rest of the file does.\n\nEnumerate git-show because it includes the description as well.\n\nMention porcelain commands before plumbing commands because I guess that\nthe paragraph is read more frequently in their context.\n\nSigned-off-by: Johannes Sixt \n---\n Documentation/diff-generate-patch.txt | 20 ++++++++++++--------\n 1 file changed, 12 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt\nindex f10ca410ad..c482c94e6b 100644\n--- a/Documentation/diff-generate-patch.txt\n+++ b/Documentation/diff-generate-patch.txt\n@@ -1,11 +1,15 @@\n-Generating patches with -p\n---------------------------\n-\n-When \"git-diff-index\", \"git-diff-tree\", or \"git-diff-files\" are run\n-with a `-p` option, \"git diff\" without the `--raw` option, or\n-\"git log\" with the \"-p\" option, they\n-do not produce the output described above; instead they produce a\n-patch file. You can customize the creation of such patches via the\n+Generating patch text with -p\n+-----------------------------\n+\n+Running\n+linkgit:git-diff[1],\n+linkgit:git-log[1],\n+linkgit:git-show[1],\n+linkgit:git-diff-index[1],\n+linkgit:git-diff-tree[1], or\n+linkgit:git-diff-files[1]\n+with the `-p` option produces patch text.\n+You can customize the creation of patch text 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-- \n2.23.0.95.gcfbaf7d16f\n"},{"id":"382513","messageId":"CAN0heSriy3AQanFpdCNTeu0Gzc1cM0hj=Eaez=9RVRAqD26+mA@mail.gmail.com","threadId":"51853","inReplyTo":"76602d23-f2b2-4a15-21ad-7bd91a4b5e44@kdbg.org","subject":"Re: [PATCH v2 1/2] diff, log doc: say \"patch text\" instead of \"patches\"","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2019-09-17T18:40:10Z","receivedAt":"2019-09-17T18:40:23Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Mon, 16 Sep 2019 at 22:46, Johannes Sixt wrote:\n>\n> Am 16.09.19 um 21:58 schrieb Junio C Hamano:\n> > I wonder if the result becomes even clearer if we dropped \"instead\n> > of the usual output\". It is a given that presence of an option\n> > would change the behaviour, so \"instead of the usual\" does not add\n> > any value in the context of the explanation we are giving.\n>\n> Agreed.\n>\n> > Also I question the value of the \"running git diff without --raw\n> > option\" sentence; \"diff --stat\" is also a way to suppress the patch\n> > text and see only the overview; I know it is not a new problem this\n> > patch introduces, but the objective of this patch is clarify about\n> > the generation of output in patch format, so...\n>\n> You have a point here, too.\n>\n> Below is v2 of just patch 1/2. 2/2 remains unchanged. I've added\n> git-show to the enumeration.\n\nYeah, this makes sense. Tested -- this renders fine.\n\nMartin\n"}]}