Re: email as a bona fide git transport

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 17, 2019, 03:17 UTC
Message-ID: <xmqqeezc83i6.fsf@gitster-ct.c.googlers.com>
In-Reply-To: <b9fb52b8-8168-6bf0-9a72-1e6c44a281a5@oracle.com>

Vegard Nossum <vegard.nossum@oracle.com> writes:

Show 8 quoted lines

> Step 1:
>
> * git send-email needs to include parent SHA1s and generally all the
>   information needed to perfectly recreate the commit when applied so
>   that all the SHA1s remain the same
>
> * git am (or an alternative command) needs to recreate the commit
>   perfectly when applied, including applying it to the correct parent

You can record and convey the commit object name a series is meant to be applied on top already, and it in general is a good way to give a wider context in order to explain and justify the series.

On the other hand, "all the information needed to recreate..." is not very useful. If you want the commit object to be exactly what you want to see at the tip of the end result, you are better off asking your upstream to pull. Using e-mail for that makes you and project participants give up a lot of benefits the workflow based on e-mail gives you, the biggest of which is the ease of giving suggestions for improvements. Once you insist "perfectly recreate the commit", you are not willing to take any input from the sidelines---worse yet, you are even dictating when the upstream runs "git am" to turn them into commits, and do so without reading the patches (there is no point reviewing as the person who runs "git am" is not even allowed to fix typo or make obvious fixes to the code, which will fail to perfectly recreate the commit).

In short, one should resist temptation to bring up "perfect reproduction" when one talks about e-mail workflow.

Show 5 quoted lines

> * Instead of describing a patchset in a separate introduction email, we
>   can create a merge commit between the parent of the first commit in
>   the series and the last and put the patchset description in the merge
>   commit [5]. This means the patchset description also gets to be part
>   of git history.

This has been done with tools around git-core, and merits a more official support. When merging a topic, it is a good idea to explain in the merge commit that brings in the topic to the mainline what the topic is about, and at least in the past few years Linus and other maintainers both within and outside the kernel have been doing so. The cover-letter material in [PATCH 00/NN] obviously can help those integrators when they write the merge message.

>   (This would require support for git send-email/am to be able to send
>   and apply merge commits -- at least those which have the same tree as
>   one of the parents. This is _not_ yet supported in my proposed git
>   patches.)

This does not require much from format-patch and am. All you need to do is to ensure that they can handle an empty commit. What you need more is a support in merge. The outline for the workflow would go like this:

 * The contributor prepares an N patch series 1/N..N/N on a single
   topic branch.

 * The summary of the series, the message that is meant to help the
   integrator, is recorded as (N+1)th commit at the tip of the topic
   branch, as an empty commit (i.e. a commit that records the same
   tree as its parent).

 * "git format-patch" is taught, when told to prepare the patch
   e-mails from such a topic branch, to notice the unusual "an empty
   commit at the tip" layout, and turn that into 0/N of the message.

 * "git am" is taught a new option to cap a topic branch made from
   patches 1/N..N/N from the incoming mbox with an extra empty
   commit, whose message is taken from the 0/N cover-letter
   material, to recreate what the contributor had in the second step
   above.

 * "git merge" is taught, when told to merge a topic branch, to
   notice the unusual "an empty commit at the tip" layout, and

   (1) merge topic~1 instead to excise the empty commit itself,

   (2) take the log message from the empty commit at the tip and use
       it to help prepare the log message of the merge.