Making a patch: "git format-patch" does not produce the documented format

Making a patch: "git format-patch" does not produce the documented format

[Dale R. Worley]

I'm working on writing a patch, but I'm running into a problem.  The
patch itself is from this commit:

    $ git log -1
    commit 07a25537909dd277426818a39d9bc4235e755383
    Author: Dale Worley <worley@ariadne.com>
    Date:   Thu Jul 18 18:43:12 2013 -0400

	open() returns -1 on failure, and indeed 0 is a possible success value
	if the user closed stdin in our process.  Fix the test.
    $ 

But the output of "git format-patch" is:

    From 07a25537909dd277426818a39d9bc4235e755383 Mon Sep 17 00:00:00 2001
    From: Dale Worley <worley@ariadne.com>
    Date: Thu, 18 Jul 2013 18:43:12 -0400
    Subject: [PATCH] open() returns -1 on failure, and indeed 0 is a possible
     success value if the user closed stdin in our process.  Fix
     the test.

    ---
     t/t0070-fundamental.sh |    7 +++++++
     wrapper.c              |    2 +-
     2 files changed, 8 insertions(+), 1 deletions(-)

    diff --git a/t/t0070-fundamental.sh b/t/t0070-fundamental.sh
    index 986b2a8..d427f3a 100755
    --- a/t/t0070-fundamental.sh
    +++ b/t/t0070-fundamental.sh
    @@ -25,6 +25,13 @@ test_expect_success POSIXPERM,SANITY 'mktemp to unwritable directory prints file
	    grep "cannotwrite/test" err
    [...]

Notice that the whole commit message has been formatted as if it is
part of the Subject line, and the line breaks in the commit message
have been refilled.

The file Documentation/SubmittingPatches says that "git format-patch"
produces patches in the best format, but the manual page shows an
example more like this:

    From 8f72bad1baf19a53459661343e21d6491c3908d3 Mon Sep 17 00:00:00 2001
    From: Tony Luck <tony.luck@intel.com>
    Date: Tue, 13 Jul 2010 11:42:54 -0700
    Subject: [PATCH] Put ia64 config files on the
    MIME-Version: 1.0
    Content-Type: text/plain; charset=UTF-8
    Content-Transfer-Encoding: 8bit

    arch/arm config files were slimmed down using a python script
    (See commit c2330e286f68f1c408b4aa6515ba49d57f05beae comment)
    [...]

That is, the first line of the commit message is in the Subject and
the remaining lines are in the message body.  As far as I can tell,
that's what SubmittingPatches prescribes.  And that is what I see in
the Git mailing list on vger.

(This is with git 1.8.3.3.)

Exactly how should the commit message be inserted into the patch
e-mail?  What needs to be updated so the code is consistent with the
documentation?

Dale

Re: Making a patch: "git format-patch" does not produce the documented format

[John Keeping]

On Wed, Jul 31, 2013 at 05:31:47PM -0400, Dale R. Worley wrote:
> Notice that the whole commit message has been formatted as if it is
> part of the Subject line, and the line breaks in the commit message
> have been refilled.
> 
> The file Documentation/SubmittingPatches says that "git format-patch"
> produces patches in the best format, but the manual page shows an
> example more like this:
> 
>     From 8f72bad1baf19a53459661343e21d6491c3908d3 Mon Sep 17 00:00:00 2001
>     From: Tony Luck <tony.luck@intel.com>
>     Date: Tue, 13 Jul 2010 11:42:54 -0700
>     Subject: [PATCH] Put ia64 config files on the
>     MIME-Version: 1.0
>     Content-Type: text/plain; charset=UTF-8
>     Content-Transfer-Encoding: 8bit
> 
>     arch/arm config files were slimmed down using a python script
>     (See commit c2330e286f68f1c408b4aa6515ba49d57f05beae comment)
>     [...]
> 
> That is, the first line of the commit message is in the Subject and
> the remaining lines are in the message body.  As far as I can tell,
> that's what SubmittingPatches prescribes.  And that is what I see in
> the Git mailing list on vger.
> 
> (This is with git 1.8.3.3.)
> 
> Exactly how should the commit message be inserted into the patch
> e-mail?  What needs to be updated so the code is consistent with the
> documentation?

git-format-patch(1) says:

        By default, the subject of a single patch is "[PATCH] " followed
        by the concatenation of lines from the commit message up to the
        first blank line (see the DISCUSSION section of git-commit(1)).

I think that accurately describes what you're seeing.  The referenced
DISCUSSION section describes how to write a commit message that is
formatted in a suitable way, with a short first subject line and then a
blank line before the body of the message.

Re: Making a patch: "git format-patch" does not produce the documented format

[Dale R. Worley]

> From: John Keeping <john@keeping.me.uk>
> 
> git-format-patch(1) says:
> 
>         By default, the subject of a single patch is "[PATCH] " followed
>         by the concatenation of lines from the commit message up to the
>         first blank line (see the DISCUSSION section of git-commit(1)).
> 
> I think that accurately describes what you're seeing.  The referenced
> DISCUSSION section describes how to write a commit message that is
> formatted in a suitable way, with a short first subject line and then a
> blank line before the body of the message.

Thanks for the confirmation.  I've figured out what is going wrong:
Documentation/SubmittingPatches says:

    The first line of the commit message should be a short description (50
    characters is the soft limit, see DISCUSSION in git-commit(1)), and
    should skip the full stop.

What it *doesn't* say is that the second line of the commit message
should be empty -- precisely so that git format-patch turns the first
line into the Subject: but does not merge the remainder of the commit
message (the "body") into the Subject: line.  Now that I know to look
for this, I can see that the commit messages in the Git repository
show this pattern.

I'm preparing some clarifications of SubmittingPatches to explain
things that a new person (e.g., me) would not know.  To fix this
issue, I am inserting:

    This first line should be a separate paragraph, that is, it should be
    followed by an empty line, which is then followed by the body of the
    commit message.

Dale

Re: Making a patch: "git format-patch" does not produce the documented format

[Junio C Hamano]

worley@alum.mit.edu (Dale R. Worley) writes:

> I'm preparing some clarifications of SubmittingPatches to explain
> things that a new person (e.g., me) would not know.

I am not sure if SubmittingPatches is a good place, though.
The document is a guidance for people who contribute to _this_
project.

But the specialness of the first paragraph applies to any project
that uses Git, so people other than those who contribute to this
project should be aware of it.

Originally we literally used "first line", but that made many things
like shortlog output and patch Subject: useless when people write a
block of text starting from the first line without a title.  Also
after resurrecting such a text from e-mail, "am" couldn't tell if
the "first line" on the "Subject:" is meant to be the first line of
the same first paragraph (which is not what we encourage), or it is
properly a single line title, and need a blank line before the first
line of the body.  So quite a while ago, we changed the rule to take
"the first paragraph" and use that in these places where we want to
give a title of a patch.