Re: [PATCH v2] Documentation: summarize how format-patch output is consumed

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 14, 2011, 22:05 UTC
Message-ID: <7vlizcfpz8.fsf@alter.siamese.dyndns.org>
In-Reply-To: <20110414211125.GA15277@elie>

Jonathan Nieder <jrnieder@gmail.com> writes:

> It would be nice to clarify use of the "From:",
> "Date:", and "Subject:" fields after the scissors in general, but this
> patch avoids the topic in hope of leading the reader to look to
> git-am(1) for a detailed discussion.

That is going backwards. The new discussion section is to help people who send e-mails using the output of this command, and the information you are leaving out is more useful to these people to decide what to cut and what to keep. The users of "am" do not have make the choice to begin with.

> I didn't find a way to sneak in a comment about "file" magic; that can
> come another day.

Heh, you could have done something like:

> +DISCUSSION
> +----------
> +The patch produced by 'git format-patch' is in UNIX mailbox format,
> +like so:

    -like so:
    +with a fixed "magic" datestamp to help people recognize that such a file
    +is an output from format-patch and not a real mailbox, like so:

if you really wanted to ;-).

Show 6 quoted lines

> +Typically it will be placed in a MUA's drafts folder, edited to add
> +timely commentary that should not go in the changelog after the three
> +dashes, and then sent as a message whose body starts with "arch/arm
> +config files were".  On the receiving end, readers can save
> +interesting patches in a UNIX mailbox and apply them with
> +linkgit:git-am[1].

Good.  I would suggest rephrasing the next paragraph, though.

> +'git am --scissors' accepts an alternative format with the patch
> +inline in the message:

-'git am --scissors' accepts an alternative format with the patch -inline in the message: +When sending a patch as part of an ongoing discussion, the patch generated +by 'git format-patch' can be to take advantage of `git am --scissors` +feature. After writing your response to the discussion, write a line that +consists solely of "-- >8 --" (scissors), append the patch, and remove +unnecessary header fields, like this:

Show 12 quoted lines

> +------------
> +...
> +> So we should do such-and-such.
> +
> +Makes sense to me.  How about this patch?
> +
> +-- >8 --
> +Subject: [IA64] Put ia64 config files on the Uwe Kleine-König diet
> +
> +arch/arm config files were slimmed down using a python script
> +...
> +------------

+Note that when used this way, most often you are sending your own patch, +so you should omit From: and Date: lines from the patch file, together +with the "From $SHA-1 $magic_timestamp" marker. Also your patch title +is likely to be different from the subject of the discussion you are +sending this response to, so it is likely that you would want to keep the +Subject: line, like the example above. +

> +See linkgit:git-am[1] for details.
> +

> -linkgit:git-am[1], linkgit:git-send-email[1]
> +linkgit:git-am[1], linkgit:git-send-email[1], linkgit:git-imap-send[1],
> +Documentation/SubmittingPatches

Hmm, I suspect this is (1) bad because the end users without the source may not have access to it, and (2) bad because it may indicate that there are hints and tricks in SubmittingPatches file, which narrowly targets developers of this project, but they would also be helpful to the general audience. Perhaps some text needs moving from there to here?