From: Yann Dirson <ydirson@altern.org>
Date: Sun, 05 Jul 2009 23:05:29 GMT
Subject: [PATCH 2/2] Improve doc for format-patch threading options.
Message-ID: <9820c7a185de928cf693a21a68d8550afe36d354.1246834884.git.ydirson@altern.org>
In-Reply-To: <112440b74f47290e55209b23d1bfc66ed2423297.1246834884.git.ydirson@altern.org>

It was not immediately clear to me that not specifying any threading
at all would result in a deep-threading because of send-email.

Signed-off-by: Yann Dirson <ydirson@altern.org>
---
 Documentation/git-format-patch.txt |   15 +++++++++++----
 Documentation/git-send-email.txt   |   16 +++++++++++-----
 2 files changed, 22 insertions(+), 9 deletions(-)

diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index 6f1fc80..ebc8b16 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -10,7 +10,7 @@ SYNOPSIS
 --------
 [verse]
 'git format-patch' [-k] [(-o|--output-directory) <dir> | --stdout]
-		   [--thread[=<style>]]
+		   [--no-thread | --thread[=<style>]]
 		   [(--attach|--inline)[=<boundary>] | --no-attach]
 		   [-s | --signoff]
 		   [-n | --numbered | -N | --no-numbered]
@@ -124,6 +124,7 @@ include::diff-options.txt[]
 	second part, with "Content-Disposition: inline".
 
 --thread[=<style>]::
+--no-thread::
 	Add In-Reply-To and References headers to make the second and
 	subsequent mails appear as replies to the first.  Also generates
 	the Message-Id header to reference.
@@ -132,9 +133,15 @@ The optional <style> argument can be either `shallow` or `deep`.
 'shallow' threading makes every mail a reply to the head of the
 series, where the head is chosen from the cover letter, the
 `\--in-reply-to`, and the first patch mail, in this order.  'deep'
-threading makes every mail a reply to the previous one.  If not
-specified, defaults to the 'format.thread' configuration, or `shallow`
-if that is not set.
+threading makes every mail a reply to the previous one.
++
+The default is --no-thread, unless the 'format.thread' configuration
+is set.  If --thread is specified without a style, it defaults to the
+style specified by 'format.thread' if any, or else `shallow`.
++
+Beware that the default for 'git send-email' is to do deep threading
+if the emails to be sent have no Message-Id header, which is what
+happens when then are generated by 'git format-patch --no-thread'.
 
 --in-reply-to=Message-Id::
 	Make the first mail (or all the mails with --no-thread) appear as a
diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
index fbde2d3..177fc93 100644
--- a/Documentation/git-send-email.txt
+++ b/Documentation/git-send-email.txt
@@ -212,11 +212,17 @@ specified, as well as 'body' if --no-signed-off-cc is specified.
 	value; if that is unspecified, default to --no-suppress-from.
 
 --[no-]thread::
-	If this is set, the In-Reply-To header will be set on each email sent.
-	If disabled with "--no-thread", no emails will have the In-Reply-To
-	header set, unless specified with --in-reply-to.
-	Default is the value of the 'sendemail.thread' configuration
-	value; if that is unspecified, default to --thread.
+	If this is set, the In-Reply-To header will be set on each
+	email sent, refering to the previous email (`deep` threading
+	per 'git format-patch' wording).
++
+If disabled with "--no-thread", no emails will have the In-Reply-To
+header set, unless specified with --in-reply-to.  Default is the value
+of the 'sendemail.thread' configuration value; if that is unspecified,
+default to --thread.
++
+Please note that this setting is independant from the similarly-named
+flag of 'git format-patch'.
 
 
 Administering
-- 
1.6.3.3