Re: [PATCH/RFC] Documentation/format-patch: summarize patch-sending workflow

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 13, 2011, 22:38 UTC
Message-ID: <7vzkntkc9d.fsf@alter.siamese.dyndns.org>
In-Reply-To: <20110413221736.GA773@elie>

Jonathan Nieder <jrnieder@gmail.com> writes:

Show 17 quoted lines

> + ...
> +'git am --scissors' accepts an alternative format with the patch
> +inline in the message:
> +
> +------------
> +...
> +> So we should do such-and-such.
> +
> +Makes sense to me.  How about this patch?
> +
> +-- 8< --
> +From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> +Subject: Makefile: extract Q_() source strings as ngettext()
> +
> +The patch adding the Q_() wrapper function around ngettext[1] didn't
> +....
> +------------

It still is preferred to remove the magic "From xxxx Mon Sep 17 00:00:00 2001" we placed to help somebody who is inclined to write an /etc/magic entry to detect files of format-patch output type if you use the scissors format.

One thing that we probably would want to clarify is use of the "From:" and the "Subject:" fields after the scissors in such a context.

"How about this patch?" is most likely to be written by the same person as the message is coming from, so I think you would rarely need a "From:" after the scissors. On the other hand, in such a message, you would come up with a potential solution to a problem raised in a discussion, and the original subject would likely to be about a description of the problem or a request for help, while the patch title would be about the solution, so it is very likely that you would want to have a "Subject:" line after the scissors.

Scissors can run in either direction; I am right handed and tend to write them as "-- >8 --", but your example is for a left handed person. Either is fine.

Other than that, looks good to me.