{"thread":{"id":"55384","subject":"[PATCH] format-patch: give an overview of what a \"patch\" message is","startedAt":"2021-03-25T10:56:02Z","lastAt":"2021-03-26T22:42:46Z","messageCount":5,"participants":["Bagas Sanjaya","Junio C Hamano","Jeff King"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"420184","messageId":"20210325105433.43310-1-bagasdotme@gmail.com","threadId":"55384","inReplyTo":null,"subject":"[PATCH] format-patch: give an overview of what a \"patch\" message is","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-03-25T10:54:34Z","receivedAt":"2021-03-25T10:56:02Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"The text says something called a \"patch\" is prepared one for each\ncommit, it is suitable for e-mail submission, and \"am\" is the\ncommand to use it, but does not say what the \"patch\" really is. The\ndescription in the page also refers to \"three-dash\" line, but that\nis totally unclear unless the reader is given a more detailed\noverview of what the \"patch\" the first paragraph refers to.\n\nCo-authored-by: Junio C Hamano \nSigned-off-by: Junio C Hamano \nSigned-off-by: Bagas Sanjaya \n---\n\nThis patch is from discussion on [1]. Junio said that rather than\nadd a new section describing the format of format-patch generated\npatches, extend the first paragraph of Description to better\nreflect that format.\n\n[1]: https://lore.kernel.org/git/xmqqeeg4zbyz.fsf@gitster.g/\n\n Documentation/git-format-patch.txt | 21 +++++++++++++++++++--\n 1 file changed, 19 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt\nindex 3e49bf2210..5cd8578b6f 100644\n--- a/Documentation/git-format-patch.txt\n+++ b/Documentation/git-format-patch.txt\n@@ -36,11 +36,28 @@ SYNOPSIS\n DESCRIPTION\n -----------\n \n-Prepare each commit with its patch in\n-one file per commit, formatted to resemble UNIX mailbox format.\n+Prepare each commit with its \"patch\" in\n+one \"message\" per commit, formatted to resemble a UNIX mailbox.\n The output of this command is convenient for e-mail submission or\n for use with 'git am'.\n \n+A \"message\" generated by the command consists of three parts:\n+\n+* A brief metadata header that begins with `From `\n+ with a fixed `Mon Sep 17 00:00:00 2001` datestamp to help programs\n+ like \"file(1)\" to recognize that the file is an output from this\n+ command, fields that record the author identity, the author date,\n+ and the title of the change (taken from the first paragraph of the\n+ commit log message).\n+\n+* The second and subsequent paragraphs of the commit log message.\n+\n+* The \"patch\", which is the \"diff -p --stat\" output (see\n+ linkgit:git-diff[1]) between the commit and its parent.\n+\n+The log message and the patch is separated by a line with a\n+three-dash line.\n+\n There are two ways to specify which commits to operate on.\n \n 1. A single commit, , specifies that the commits leading\n-- \n2.25.1\n\n"},{"id":"420205","messageId":"xmqqmturuh8o.fsf@gitster.g","threadId":"55384","inReplyTo":"20210325105433.43310-1-bagasdotme@gmail.com","subject":"Re: [PATCH] format-patch: give an overview of what a \"patch\" message is","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-03-25T20:10:31Z","receivedAt":"2021-03-25T20:11:12Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Bagas Sanjaya writes:\n\n> The text says something called a \"patch\" is prepared one for each\n> commit, it is suitable for e-mail submission, and \"am\" is the\n> command to use it, but does not say what the \"patch\" really is. The\n> description in the page also refers to \"three-dash\" line, but that\n> is totally unclear unless the reader is given a more detailed\n> overview of what the \"patch\" the first paragraph refers to.\n>\n> Co-authored-by: Junio C Hamano \n> Signed-off-by: Junio C Hamano \n> Signed-off-by: Bagas Sanjaya \n> ---\n\nI do not think this was co-authored; you are forwarding somebody\nelse's patch that was written without any input from you.\n"},{"id":"420242","messageId":"7c0aabe0-9240-950e-912f-0a195db7a144@gmail.com","threadId":"55384","inReplyTo":"xmqqmturuh8o.fsf@gitster.g","subject":"Re: [PATCH] format-patch: give an overview of what a \"patch\" message is","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-03-26T08:26:25Z","receivedAt":"2021-03-26T08:27:02Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"On 26/03/21 03.10, Junio C Hamano wrote:\n> Bagas Sanjaya writes:\n> \n>> The text says something called a \"patch\" is prepared one for each\n>> commit, it is suitable for e-mail submission, and \"am\" is the\n>> command to use it, but does not say what the \"patch\" really is. The\n>> description in the page also refers to \"three-dash\" line, but that\n>> is totally unclear unless the reader is given a more detailed\n>> overview of what the \"patch\" the first paragraph refers to.\n>>\n>> Co-authored-by: Junio C Hamano \n>> Signed-off-by: Junio C Hamano \n>> Signed-off-by: Bagas Sanjaya \n>> ---\n> \n> I do not think this was co-authored; you are forwarding somebody\n> else's patch that was written without any input from you.\n> \nOh dear...\n\nNext time when I need to send patches forwarded from you (or others),\nbut not necessarily Co-authored-by, what should I do? Something like\nthis note below?\n\n[forwarded from someone]\n\n-- \nAn old man doll... just what I always wanted! - Clara\n"},{"id":"420245","messageId":"YF2fIhVUwBim47Wq@coredump.intra.peff.net","threadId":"55384","inReplyTo":"7c0aabe0-9240-950e-912f-0a195db7a144@gmail.com","subject":"Re: [PATCH] format-patch: give an overview of what a \"patch\" message is","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-03-26T08:45:22Z","receivedAt":"2021-03-26T08:46:11Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Fri, Mar 26, 2021 at 03:26:25PM +0700, Bagas Sanjaya wrote:\n\n> On 26/03/21 03.10, Junio C Hamano wrote:\n> > Bagas Sanjaya writes:\n> > \n> > > The text says something called a \"patch\" is prepared one for each\n> > > commit, it is suitable for e-mail submission, and \"am\" is the\n> > > command to use it, but does not say what the \"patch\" really is. The\n> > > description in the page also refers to \"three-dash\" line, but that\n> > > is totally unclear unless the reader is given a more detailed\n> > > overview of what the \"patch\" the first paragraph refers to.\n> > > \n> > > Co-authored-by: Junio C Hamano \n> > > Signed-off-by: Junio C Hamano \n> > > Signed-off-by: Bagas Sanjaya \n> > > ---\n> > \n> > I do not think this was co-authored; you are forwarding somebody\n> > else's patch that was written without any input from you.\n> > \n> Oh dear...\n> \n> Next time when I need to send patches forwarded from you (or others),\n> but not necessarily Co-authored-by, what should I do? Something like\n> this note below?\n> \n> [forwarded from someone]\n\nYou should start the first line of the message body with:\n\n From: Original Author \n\ngit-send-email will do this automatically if the author of the commit you\nare sending does not match your identity (you may also need to use \"git\ncommit --author\" to make sure the author is set correctly in the\ncommit).\n\n-Peff\n"},{"id":"420287","messageId":"xmqqa6qpsfke.fsf@gitster.g","threadId":"55384","inReplyTo":"YF2fIhVUwBim47Wq@coredump.intra.peff.net","subject":"Re: [PATCH] format-patch: give an overview of what a \"patch\" message is","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-03-26T22:41:53Z","receivedAt":"2021-03-26T22:42:46Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> You should start the first line of the message body with:\n>\n> From: Original Author \n>\n> git-send-email will do this automatically if the author of the commit you\n> are sending does not match your identity (you may also need to use \"git\n> commit --author\" to make sure the author is set correctly in the\n> commit).\n\nThanks.\n\nFYI, the commit in question is 28e29ee3 (format-patch: give an\noverview of what a \"patch\" message is, 2021-03-24) and I think it is\nready for 'next'.\n"}]}