[WIP PATCH 0/2] format-patch / send-mail thrading documentation

[WIP PATCH 0/2] format-patch / send-mail thrading documentation

[Yann Dirson]

While sending patches, it took me time to realize that it was not just
the format-patch --thread documentation being inaccurate, but that the
interactions with send-email were not obvious - and that the config
items specific to send-email were not at all described in the central
config.txt.

Now that bizarre interaction may just be due to a bug that we'd like
to fix instead ?

Yann Dirson (2):
  List send-email config options in config.txt.
  Improve doc for format-patch threading options.

 Documentation/config.txt           |   40 ++++++++++++++++++++++++++++++++++++
 Documentation/git-format-patch.txt |   15 +++++++++---
 Documentation/git-send-email.txt   |   16 +++++++++----
 3 files changed, 62 insertions(+), 9 deletions(-)

[PATCH 1/2] List send-email config options in config.txt.

[Yann Dirson]

Signed-off-by: Yann Dirson <ydirson@altern.org>
---
 Documentation/config.txt |   40 ++++++++++++++++++++++++++++++++++++++++
 1 files changed, 40 insertions(+), 0 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 2fecbe3..55fa938 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -1379,6 +1379,46 @@ rerere.enabled::
 	default enabled if you create `rr-cache` directory under
 	`$GIT_DIR`, but can be disabled by setting this option to false.
 
+sendemail.aliasesfile::
+	To avoid typing long email addresses, point this to one or more
+	email aliases files.  You must also supply 'sendemail.aliasfiletype'.
+
+sendemail.aliasfiletype::
+	Format of the file(s) specified in sendemail.aliasesfile. Must be
+	one of 'mutt', 'mailrc', 'pine', 'elm', or 'gnus'.
+
+sendemail.bcc::
+sendemail.cc::
+sendemail.cccmd::
+sendemail.chainreplyto::
+
+sendemail.confirm::
+	Sets the default for whether to confirm before sending. Must be
+	one of 'always', 'never', 'cc', 'compose', or 'auto'. See '--confirm'
+	in the previous section for the meaning of these values.
+
+sendemail.multiedit::
+	If true (default), a single editor instance will be spawned to edit
+	files you have to edit (patches when '--annotate' is used, and the
+	summary when '--compose' is used). If false, files will be edited one
+	after the other, spawning a new editor each time.
+
+sendemail.envelopesender::
+sendemail.from::
+sendemail.identity::
+sendemail.<identity>.*::
+sendemail.signedoffbycc::
+sendemail.smtpencryption::
+sendemail.smtppass::
+sendemail.suppresscc::
+sendemail.suppressfrom::
+sendemail.to::
+sendemail.smtpserver::
+sendemail.smtpserverport::
+sendemail.smtpuser::
+sendemail.thread::
+sendemail.validate::
+
 showbranch.default::
 	The default set of branches for linkgit:git-show-branch[1].
 	See linkgit:git-show-branch[1].
-- 
1.6.3.3

[PATCH 2/2] Improve doc for format-patch threading options.

[Yann Dirson]

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

Re: [PATCH 2/2] Improve doc for format-patch threading options.

[Markus Heidelberg]

Yann Dirson, 06.07.2009:
> 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::

Maybe also add a sentence like "If this is set..." as in the
git-send-email documentation below, else the --no-thread will be
confusing.

>  	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'.
                ^^^^
they

> 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

You should add "by default refering ...", because it can be changed to
shallow threading with --no-chain-reply-to. Maybe also note that this is
changeable here just to get the relation to shallow from format-patch?

> +	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

Re: [PATCH 2/2] Improve doc for format-patch threading options.

[Markus Heidelberg]

Yann Dirson, 06.07.2009:
> +++ b/Documentation/git-format-patch.txt
> @@ -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'.

Oh, due to the typo I mentioned in my previous mail, I forgot to really
comment.

The last paragraph is misleading. git-send-email always adds headers for
deep threading by default, regardless of any existing Message-Id
headers.
The current wording makes one believe, git-send-email respects existing
headers if the patches are created with 'git format-patch --thread'.
But that it isn't aware of them is exactly what you want to explain
here.

Re: [PATCH 2/2] Improve doc for format-patch threading options.

[Yann Dirson]

On Mon, Jul 06, 2009 at 10:49:29AM +0200, Markus Heidelberg wrote:
> Yann Dirson, 06.07.2009:
> > +++ b/Documentation/git-format-patch.txt
> > @@ -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'.
> 
> Oh, due to the typo I mentioned in my previous mail, I forgot to really
> comment.
> 
> The last paragraph is misleading. git-send-email always adds headers for
> deep threading by default, regardless of any existing Message-Id
> headers.
> The current wording makes one believe, git-send-email respects existing
> headers if the patches are created with 'git format-patch --thread'.
> But that it isn't aware of them is exactly what you want to explain
> here.

Indeed I realize that I did not grasp correctly how things are
supposed to fit together.  Reading the code and experimenting, I see
that:

- as you say, send-email completely ignores any pre-existing
In-Reply-To and References header (it does keep the Message-Id's,
though)

- send-email simply adds its own In-Reply-To and References headers.
That IMHO does not make any sense, and the behaviour of such a thing
is likely to vary among MUAs (if it even does not violate the
standards, which I did not check)

- even when --no-thread is specified, and format-patch was run with
--no-thread as well, it still adds In-Reply-To and References headers,
and I must say I do not see what in the code causes this behaviour.

Looks like we should clarify things first, and possibly fix things,
before we can start to document them - or did I miss some point that
would seem obvious to others ?

Re: [PATCH 2/2] Improve doc for format-patch threading options.

[Markus Heidelberg]

Yann Dirson, 17.07.2009:
> On Mon, Jul 06, 2009 at 10:49:29AM +0200, Markus Heidelberg wrote:
> > Yann Dirson, 06.07.2009:
> > > +++ b/Documentation/git-format-patch.txt
> > > @@ -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'.
> > 
> > Oh, due to the typo I mentioned in my previous mail, I forgot to really
> > comment.
> > 
> > The last paragraph is misleading. git-send-email always adds headers for
> > deep threading by default, regardless of any existing Message-Id
> > headers.
> > The current wording makes one believe, git-send-email respects existing
> > headers if the patches are created with 'git format-patch --thread'.
> > But that it isn't aware of them is exactly what you want to explain
> > here.
> 
> Indeed I realize that I did not grasp correctly how things are
> supposed to fit together.  Reading the code and experimenting, I see
> that:
> 
> - as you say, send-email completely ignores any pre-existing
> In-Reply-To and References header (it does keep the Message-Id's,
> though)
> 
> - send-email simply adds its own In-Reply-To and References headers.
> That IMHO does not make any sense, and the behaviour of such a thing
> is likely to vary among MUAs (if it even does not violate the
> standards, which I did not check)

I don't know either, but funny things often cause trouble. send-email
would have to parse the patch to avoid adding its own headers. The
easiest solution/workaround is that the user should know, whether he
does the threading with format-patch or send-email. This is error, of
course.

See also this recent thread about the same:
http://thread.gmane.org/gmane.comp.version-control.git/122554/focus=122584

> - even when --no-thread is specified, and format-patch was run with
> --no-thread as well, it still adds In-Reply-To and References headers,
> and I must say I do not see what in the code causes this behaviour.

This is caused by a bug fixed in commit 5e9758e29 (send-email: fix
non-threaded mails, 2009-06-12). Try using "git send-email --no-thread
--no-chain-reply" and it may work again. You should use an up-to-date
git, when searching for bugs.

Markus

Re: [PATCH 2/2] Improve doc for format-patch threading options.

[Yann Dirson]

On Fri, Jul 17, 2009 at 12:58:46AM +0200, Markus Heidelberg wrote:
> > - even when --no-thread is specified, and format-patch was run with
> > --no-thread as well, it still adds In-Reply-To and References headers,
> > and I must say I do not see what in the code causes this behaviour.
> 
> This is caused by a bug fixed in commit 5e9758e29 (send-email: fix
> non-threaded mails, 2009-06-12). Try using "git send-email --no-thread
> --no-chain-reply" and it may work again. You should use an up-to-date
> git, when searching for bugs.

I had tried exactly this just in case it would help, with current
master (1.6.4rc1), and it still saw the same behaviour.

Re: [PATCH 2/2] Improve doc for format-patch threading options.

[Markus Heidelberg]

Yann Dirson, 17.07.2009:
> On Fri, Jul 17, 2009 at 12:58:46AM +0200, Markus Heidelberg wrote:
> > > - even when --no-thread is specified, and format-patch was run with
> > > --no-thread as well, it still adds In-Reply-To and References headers,
> > > and I must say I do not see what in the code causes this behaviour.
> > 
> > This is caused by a bug fixed in commit 5e9758e29 (send-email: fix
> > non-threaded mails, 2009-06-12). Try using "git send-email --no-thread
> > --no-chain-reply" and it may work again. You should use an up-to-date
> > git, when searching for bugs.
> 
> I had tried exactly this just in case it would help, with current
> master (1.6.4rc1), and it still saw the same behaviour.

Strange, I can't reproduce it.

Re: [PATCH 2/2] Improve doc for format-patch threading options.

[Yann Dirson]

On Sat, Jul 18, 2009 at 01:23:41AM +0200, Markus Heidelberg wrote:
> Yann Dirson, 17.07.2009:
> > On Fri, Jul 17, 2009 at 12:58:46AM +0200, Markus Heidelberg wrote:
> > > > - even when --no-thread is specified, and format-patch was run with
> > > > --no-thread as well, it still adds In-Reply-To and References headers,
> > > > and I must say I do not see what in the code causes this behaviour.
> > > 
> > > This is caused by a bug fixed in commit 5e9758e29 (send-email: fix
> > > non-threaded mails, 2009-06-12). Try using "git send-email --no-thread
> > > --no-chain-reply" and it may work again. You should use an up-to-date
> > > git, when searching for bugs.
> > 
> > I had tried exactly this just in case it would help, with current
> > master (1.6.4rc1), and it still saw the same behaviour.
> 
> Strange, I can't reproduce it.

You're right, I must have forgotten --exec-path=$PWD when doing my
tests.  It also works with "git send-email --no-thread",
--no-chain-reply is (as expected) not even necessary.

Cool, I can get back to documenting that :)

Re: [PATCH 1/2] List send-email config options in config.txt.

[Junio C Hamano]

Yann Dirson <ydirson@altern.org> writes:

> Signed-off-by: Yann Dirson <ydirson@altern.org>
> ---
>  Documentation/config.txt |   40 ++++++++++++++++++++++++++++++++++++++++
>  1 files changed, 40 insertions(+), 0 deletions(-)
>
> diff --git a/Documentation/config.txt b/Documentation/config.txt
> index 2fecbe3..55fa938 100644
> --- a/Documentation/config.txt
> +++ b/Documentation/config.txt
> @@ -1379,6 +1379,46 @@ rerere.enabled::
>  	default enabled if you create `rr-cache` directory under
>  	`$GIT_DIR`, but can be disabled by setting this option to false.
>  
> +sendemail.aliasesfile::
> +	To avoid typing long email addresses, point this to one or more
> +	email aliases files.  You must also supply 'sendemail.aliasfiletype'.
> +
> +sendemail.aliasfiletype::
> +	Format of the file(s) specified in sendemail.aliasesfile. Must be
> +	one of 'mutt', 'mailrc', 'pine', 'elm', or 'gnus'.
> +
> +sendemail.bcc::
> +sendemail.cc::
> +sendemail.cccmd::
> +sendemail.chainreplyto::
> +

At least, we would want to have some description for these.  Something
along the lines of "Specifies values used for the corresponding command
line options when they are not given." should suffice.

> +sendemail.confirm::
> +	Sets the default for whether to confirm before sending. Must be
> +	one of 'always', 'never', 'cc', 'compose', or 'auto'. See '--confirm'
> +	in the previous section for the meaning of these values.
> +
> +sendemail.multiedit::
> +	If true (default), a single editor instance will be spawned to edit
> +	files you have to edit (patches when '--annotate' is used, and the
> +	summary when '--compose' is used). If false, files will be edited one
> +	after the other, spawning a new editor each time.
> +
> +sendemail.envelopesender::
> +sendemail.from::
> +sendemail.identity::
> +sendemail.<identity>.*::
> +sendemail.signedoffbycc::
> +sendemail.smtpencryption::
> +sendemail.smtppass::
> +sendemail.suppresscc::
> +sendemail.suppressfrom::
> +sendemail.to::
> +sendemail.smtpserver::
> +sendemail.smtpserverport::
> +sendemail.smtpuser::
> +sendemail.thread::
> +sendemail.validate::
> +

Likewise.

>  showbranch.default::
>  	The default set of branches for linkgit:git-show-branch[1].
>  	See linkgit:git-show-branch[1].
> -- 
> 1.6.3.3

Re: [PATCH 1/2] List send-email config options in config.txt.

[Yann Dirson]

On Sun, Jul 05, 2009 at 11:58:01PM -0700, Junio C Hamano wrote:
> > +sendemail.aliasesfile::
> > +	To avoid typing long email addresses, point this to one or more
> > +	email aliases files.  You must also supply 'sendemail.aliasfiletype'.
> > +
> > +sendemail.aliasfiletype::
> > +	Format of the file(s) specified in sendemail.aliasesfile. Must be
> > +	one of 'mutt', 'mailrc', 'pine', 'elm', or 'gnus'.
> > +
> > +sendemail.bcc::
> > +sendemail.cc::
> > +sendemail.cccmd::
> > +sendemail.chainreplyto::
> > +
> 
> At least, we would want to have some description for these.  Something
> along the lines of "Specifies values used for the corresponding command
> line options when they are not given." should suffice.

Sure - that's part of why this series reads WIP :)

I'm also not entirely satisfied with duplicating the existing
descriptions from the send-email manpage, like I have done for those
with a desctiption.  We could just mention all the flags with a "See
linkgit:git-send-email[1] for details.", although it looks a bit
inconsistent with the common usage, before going into a massive
migration of these parameters into config.txt.

Would that be seen as reasonable ?

[PATCHv2 0/2] format-patch / send-mail threading documentation

[Yann Dirson]

This new series attempts to correct things to take into account
comments from Junio and Markus, and to avoid duplication of config
item descriptions into config.txt.

Yann Dirson (2):
  List send-email config options in config.txt.
  Improve doc for format-patch threading options.

 Documentation/config.txt           |   44 ++++++++++++++++++++++++++++++++++++
 Documentation/git-format-patch.txt |   22 ++++++++++++-----
 Documentation/git-send-email.txt   |   21 +++++++++++++----
 3 files changed, 75 insertions(+), 12 deletions(-)

[PATCH 1/2] List send-email config options in config.txt.

[Yann Dirson]

Also mention deprecated aliases that do not appear in the send-email
manpage.

Signed-off-by: Yann Dirson <ydirson@altern.org>
---
 Documentation/config.txt |   44 ++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 44 insertions(+), 0 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index cb6832b..6857d2f 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -1387,6 +1387,50 @@ rerere.enabled::
 	default enabled if you create `rr-cache` directory under
 	`$GIT_DIR`, but can be disabled by setting this option to false.
 
+sendemail.identity::
+	A configuration identity. When given, causes values in the
+	'sendemail.<identity>' subsection to take precedence over
+	values in the 'sendemail' section. The default identity is
+	the value of 'sendemail.identity'.
+
+sendemail.smtpencryption::
+	See linkgit:git-send-email[1] for description.  Note that this
+	setting is not subject to the 'identity' mechanism.
+
+sendemail.smtpssl::
+	Deprecated alias for 'sendemail.smtpencryption = ssl'.
+
+sendemail.<identity>.*::
+	Identity-specific versions of the 'sendemail.*' parameters
+	found below, taking precedence over those when the this
+	identity is selected, through command-line or
+	'sendemail.identity'.
+
+sendemail.aliasesfile::
+sendemail.aliasfiletype::
+sendemail.bcc::
+sendemail.cc::
+sendemail.cccmd::
+sendemail.chainreplyto::
+sendemail.confirm::
+sendemail.envelopesender::
+sendemail.from::
+sendemail.multiedit::
+sendemail.signedoffbycc::
+sendemail.smtppass::
+sendemail.suppresscc::
+sendemail.suppressfrom::
+sendemail.to::
+sendemail.smtpserver::
+sendemail.smtpserverport::
+sendemail.smtpuser::
+sendemail.thread::
+sendemail.validate::
+	See linkgit:git-send-email[1] for description.
+
+sendemail.signedoffcc::
+	Deprecated alias for 'sendemail.signedoffbycc'.
+
 showbranch.default::
 	The default set of branches for linkgit:git-show-branch[1].
 	See linkgit:git-show-branch[1].
-- 
1.6.4.rc1.12.g05859c

[PATCH 2/2] Improve doc for format-patch threading options.

[Yann Dirson]

This hopefully makes the relationship between threading options of
format-patch and send-email easier to grasp.

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

diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index 6f1fc80..687e667 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,17 +124,25 @@ include::diff-options.txt[]
 	second part, with "Content-Disposition: inline".
 
 --thread[=<style>]::
-	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.
+--no-thread::
+	Controls addition of In-Reply-To and References headers to
+	make the second and subsequent mails appear as replies to the
+	first.  Also controls generation of the Message-Id header to
+	reference.
 +
 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 thread emails
+itself.  If you want 'git format-patch' to take care of hreading, you
+will want to ensure that threading is disabled for 'git send-email'.
 
 --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..d6b192b 100644
--- a/Documentation/git-send-email.txt
+++ b/Documentation/git-send-email.txt
@@ -212,11 +212,22 @@ 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 and References headers will be
+	added to each email sent.  Whether each mail refers to the
+	previous email (`deep` threading per 'git format-patch'
+	wording) or to the first email (`shallow` threading) is
+	governed by "--[no-]chain-reply-to".
++
+If disabled with "--no-thread", those headers will not be added
+(unless specified with --in-reply-to).  Default is the value of the
+'sendemail.thread' configuration value; if that is unspecified,
+default to --thread.
++
+It is up to the user to ensure that no In-Reply-To header already
+exists when 'git send-email' is asked to add it (especially note that
+'git format-patch' can be configured to do the threading itself).
+Failure to do so may not produce the expected result in the
+recipient's MUA.
 
 
 Administering
-- 
1.6.4.rc1.12.g05859c

Re: [PATCH 2/2] Improve doc for format-patch threading options.

[Markus Heidelberg]

Yann Dirson, 22.07.2009:
> This hopefully makes the relationship between threading options of
> format-patch and send-email easier to grasp.

Yes, it does.

> Signed-off-by: Yann Dirson <ydirson@altern.org>
> ---
>  Documentation/git-format-patch.txt |   22 +++++++++++++++-------
>  Documentation/git-send-email.txt   |   21 ++++++++++++++++-----
>  2 files changed, 31 insertions(+), 12 deletions(-)
> 
> diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
> index 6f1fc80..687e667 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,17 +124,25 @@ include::diff-options.txt[]
>  	second part, with "Content-Disposition: inline".
>  
>  --thread[=<style>]::
> -	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.
> +--no-thread::
> +	Controls addition of In-Reply-To and References headers to
> +	make the second and subsequent mails appear as replies to the
> +	first.  Also controls generation of the Message-Id header to
> +	reference.
>  +
>  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 thread emails
> +itself.  If you want 'git format-patch' to take care of hreading, you
                                                           ^^^^^^^^
threading
I guess Junio can squash this in.

> +will want to ensure that threading is disabled for 'git send-email'.
>  
>  --in-reply-to=Message-Id::
>  	Make the first mail (or all the mails with --no-thread) appear as a

Re: [PATCHv2 0/2] format-patch / send-mail threading documentation

[Junio C Hamano]

Sounds reasonable from a cursory look.

Thanks, will queue.