Jonathan Nieder <jrnieder@xxxxxxxxx> 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 ;-).
> +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:
> +------------
> +...
> +> 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?
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html