git-send-email.perl: make initial In-Reply-To apply only to first email

When an initial --in-reply-to is supplied, make it apply only to the
first message; --[no-]chain-reply-to setting are honored by second and
subsequent messages; this is also how the git-format-patch option with
the same name behaves.

Moreover, when $initial_reply_to is asked to the user interactively it
is asked as the "Message-ID to be used as In-Reply-To for the _first_
email", this makes the user think that the second and subsequent
patches are not using it but are considered as replies to the first
message or chained according to the --[no-]chain-reply setting.

Look at the v2 series in the illustration to see what the new behavior
ensures:

       (before the patch)          |      (after the patch)
 [PATCH 0/2] Here is what I did... | [PATCH 0/2] Here is what I did...
   [PATCH 1/2] Clean up and tests  |   [PATCH 1/2] Clean up and tests
   [PATCH 2/2] Implementation      |   [PATCH 2/2] Implementation
   [PATCH v2 0/3] Here is a reroll |   [PATCH v2 0/3] Here is a reroll
   [PATCH v2 1/3] Clean up         |     [PATCH v2 1/3] Clean up
   [PATCH v2 2/3] New tests        |     [PATCH v2 2/3] New tests
   [PATCH v2 3/3] Implementation   |     [PATCH v2 3/3] Implementation

This is the typical behaviour we want when we send a series with cover
letter in reply to some discussion, the new patch series should appear
as a separate subtree in the discussion.

Also update the documentation on --in-reply-to to describe the new
behavior.

Signed-off-by: Antonio Ospite <ospite@studenti.unina.it>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

1 files changed, 20 insertions, 5 deletions

diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
index 05904e0e7f..ebc024ae3d 100644
--- a/Documentation/git-send-email.txt
+++ b/Documentation/git-send-email.txt
@@ -82,11 +82,26 @@ See the CONFIGURATION section for 'sendemail.multiedit'.
 	set, as returned by "git var -l".
 
 --in-reply-to=<identifier>::
-	Specify the contents of the first In-Reply-To header.
-	Subsequent emails will refer to the previous email
-	instead of this if --chain-reply-to is set.
-	Only necessary if --compose is also set.  If --compose
-	is not set, this will be prompted for.
+	Make the first mail (or all the mails with `--no-thread`) appear as a
+	reply to the given Message-Id, which avoids breaking threads to
+	provide a new patch series.
+	The second and subsequent emails will be sent as replies according to
+	the `--[no]-chain-reply-to` setting.
++
+So for example when `--thread` and `--no-chain-reply-to` are specified, the
+second and subsequent patches will be replies to the first one like in the
+illustration below where `[PATCH v2 0/3]` is in reply to `[PATCH 0/2]`:
++
+  [PATCH 0/2] Here is what I did...
+    [PATCH 1/2] Clean up and tests
+    [PATCH 2/2] Implementation
+    [PATCH v2 0/3] Here is a reroll
+      [PATCH v2 1/3] Clean up
+      [PATCH v2 2/3] New tests
+      [PATCH v2 3/3] Implementation
++
+Only necessary if --compose is also set.  If --compose
+is not set, this will be prompted for.
 
 --subject=<string>::
 	Specify the initial subject of the email thread.