threads / patch / 55384

patchformat-patch: give an overview of what a "patch" message is

Subject: [PATCH] format-patch: give an overview of what a "patch" message is

## tl;dr

5 messages between Mar 25, 2021 and Mar 26, 2021. Diffs are folded; open one to read it.

replies: 4people: 3as markdown or json

Bagas Sanjaya· Mar 25, 2021, 10:54 UTC · lore

The text says something called a "patch" is prepared one for each commit, it is suitable for e-mail submission, and "am" is the command to use it, but does not say what the "patch" really is. The description in the page also refers to "three-dash" line, but that is totally unclear unless the reader is given a more detailed overview of what the "patch" the first paragraph refers to.

Co-authored-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---

This patch is from discussion on [1]. Junio said that rather than add a new section describing the format of format-patch generated patches, extend the first paragraph of Description to better reflect that format.

[1]: https://lore.kernel.org/git/xmqqeeg4zbyz.fsf@gitster.g/

 Documentation/git-format-patch.txt | 21 +++++++++++++++++++--
 1 file changed, 19 insertions(+), 2 deletions(-)

Show changes to Documentation/git-format-patch.txt +19 −2

diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index 3e49bf2210..5cd8578b6f 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -36,11 +36,28 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-Prepare each commit with its patch in
-one file per commit, formatted to resemble UNIX mailbox format.
+Prepare each commit with its "patch" in
+one "message" per commit, formatted to resemble a UNIX mailbox.
 The output of this command is convenient for e-mail submission or
 for use with 'git am'.
 
+A "message" generated by the command consists of three parts:
+
+* A brief metadata header that begins with `From <commit>`
+  with a fixed `Mon Sep 17 00:00:00 2001` datestamp to help programs
+  like "file(1)" to recognize that the file is an output from this
+  command, fields that record the author identity, the author date,
+  and the title of the change (taken from the first paragraph of the
+  commit log message).
+
+* The second and subsequent paragraphs of the commit log message.
+
+* The "patch", which is the "diff -p --stat" output (see
+  linkgit:git-diff[1]) between the commit and its parent.
+
+The log message and the patch is separated by a line with a
+three-dash line.
+
 There are two ways to specify which commits to operate on.
 
 1. A single commit, <since>, specifies that the commits leading

-- 
2.25.1

Junio C Hamano· Mar 25, 2021, 20:10 UTC · re: Bagas Sanjaya · lore

Re: [PATCH] format-patch: give an overview of what a "patch" message is

Bagas Sanjaya <bagasdotme@gmail.com> writes:

Show 11 quoted lines

> The text says something called a "patch" is prepared one for each
> commit, it is suitable for e-mail submission, and "am" is the
> command to use it, but does not say what the "patch" really is.  The
> description in the page also refers to "three-dash" line, but that
> is totally unclear unless the reader is given a more detailed
> overview of what the "patch" the first paragraph refers to.
>
> Co-authored-by: Junio C Hamano <gitster@pobox.com>
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---

I do not think this was co-authored; you are forwarding somebody else's patch that was written without any input from you.

Bagas Sanjaya· Mar 26, 2021, 08:26 UTC · re: Junio C Hamano · lore

Re: [PATCH] format-patch: give an overview of what a "patch" message is

On 26/03/21 03.10, Junio C Hamano wrote:

Show 17 quoted lines

> Bagas Sanjaya <bagasdotme@gmail.com> writes:
> 
>> The text says something called a "patch" is prepared one for each
>> commit, it is suitable for e-mail submission, and "am" is the
>> command to use it, but does not say what the "patch" really is.  The
>> description in the page also refers to "three-dash" line, but that
>> is totally unclear unless the reader is given a more detailed
>> overview of what the "patch" the first paragraph refers to.
>>
>> Co-authored-by: Junio C Hamano <gitster@pobox.com>
>> Signed-off-by: Junio C Hamano <gitster@pobox.com>
>> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
>> ---
> 
> I do not think this was co-authored; you are forwarding somebody
> else's patch that was written without any input from you.
>

Oh dear...

Next time when I need to send patches forwarded from you (or others), but not necessarily Co-authored-by, what should I do? Something like this note below?

[forwarded from someone]

-- 
An old man doll... just what I always wanted! - Clara

Jeff King· Mar 26, 2021, 08:45 UTC · re: Bagas Sanjaya · lore

Re: [PATCH] format-patch: give an overview of what a "patch" message is

On Fri, Mar 26, 2021 at 03:26:25PM +0700, Bagas Sanjaya wrote:

Show 25 quoted lines

> On 26/03/21 03.10, Junio C Hamano wrote:
> > Bagas Sanjaya <bagasdotme@gmail.com> writes:
> > 
> > > The text says something called a "patch" is prepared one for each
> > > commit, it is suitable for e-mail submission, and "am" is the
> > > command to use it, but does not say what the "patch" really is.  The
> > > description in the page also refers to "three-dash" line, but that
> > > is totally unclear unless the reader is given a more detailed
> > > overview of what the "patch" the first paragraph refers to.
> > > 
> > > Co-authored-by: Junio C Hamano <gitster@pobox.com>
> > > Signed-off-by: Junio C Hamano <gitster@pobox.com>
> > > Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> > > ---
> > 
> > I do not think this was co-authored; you are forwarding somebody
> > else's patch that was written without any input from you.
> > 
> Oh dear...
> 
> Next time when I need to send patches forwarded from you (or others),
> but not necessarily Co-authored-by, what should I do? Something like
> this note below?
> 
> [forwarded from someone]

You should start the first line of the message body with:

  From: Original Author <orig@example.com>

git-send-email will do this automatically if the author of the commit you are sending does not match your identity (you may also need to use "git commit --author" to make sure the author is set correctly in the commit).

-Peff

Junio C Hamano· Mar 26, 2021, 22:41 UTC · re: Jeff King · lore

Re: [PATCH] format-patch: give an overview of what a "patch" message is

Jeff King <peff@peff.net> writes:

Show 8 quoted lines

> You should start the first line of the message body with:
>
>   From: Original Author <orig@example.com>
>
> git-send-email will do this automatically if the author of the commit you
> are sending does not match your identity (you may also need to use "git
> commit --author" to make sure the author is set correctly in the
> commit).

Thanks.

FYI, the commit in question is 28e29ee3 (format-patch: give an overview of what a "patch" message is, 2021-03-24) and I think it is ready for 'next'.