threads / patch / 20030

patch, 2 partsformat-patch / send-mail thrading documentation

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

## tl;dr

17 messages between Jul 5, 2009 and Jul 23, 2009. Diffs are folded; open one to read it.

replies: 16people: 3as markdown or json

Yann Dirson· Jul 5, 2009, 23:05 UTC · lore

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(-)
Yann Dirson· Jul 5, 2009, 23:05 UTC · re: Yann Dirson · lore

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

Signed-off-by: Yann Dirson <ydirson@altern.org>
---
 Documentation/config.txt |   40 ++++++++++++++++++++++++++++++++++++++++
 1 files changed, 40 insertions(+), 0 deletions(-)
Show changes to Documentation/config.txt +40 −0
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
Yann Dirson· Jul 5, 2009, 23:05 UTC · re: Yann Dirson · lore

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

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(-)
Show changes to 2 files +22 −9

Documentation/git-format-patch.txt, Documentation/git-send-email.txt

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
Markus Heidelberg· Jul 6, 2009, 08:36 UTC · re: Yann Dirson · lore

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

Yann Dirson, 06.07.2009:
Show 18 quoted lines
> 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.

Show 19 quoted lines
>  	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
Show 15 quoted lines
> 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?

Show 12 quoted lines
> +	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
Markus Heidelberg· Jul 6, 2009, 08:49 UTC · re: Yann Dirson · lore

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

Yann Dirson, 06.07.2009:
Show 17 quoted lines
> +++ 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.

Yann Dirson· Jul 16, 2009, 22:23 UTC · re: Markus Heidelberg · lore

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

On Mon, Jul 06, 2009 at 10:49:29AM +0200, Markus Heidelberg wrote:
Show 29 quoted lines
> 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 ?

Markus Heidelberg· Jul 16, 2009, 22:58 UTC · re: Yann Dirson · lore

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

Yann Dirson, 17.07.2009:
Show 43 quoted lines
> 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
Yann Dirson· Jul 17, 2009, 06:52 UTC · re: Markus Heidelberg · lore

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

On Fri, Jul 17, 2009 at 12:58:46AM +0200, Markus Heidelberg wrote:
Show 8 quoted lines
> > - 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.

Markus Heidelberg· Jul 17, 2009, 23:23 UTC · re: Yann Dirson · lore

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

Yann Dirson, 17.07.2009:
Show 12 quoted lines
> 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.
Yann Dirson· Jul 22, 2009, 20:57 UTC · re: Markus Heidelberg · lore

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

On Sat, Jul 18, 2009 at 01:23:41AM +0200, Markus Heidelberg wrote:
Show 15 quoted lines
> 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 :)
Junio C Hamano· Jul 6, 2009, 06:58 UTC · re: Yann Dirson · lore

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

Yann Dirson <ydirson@altern.org> writes:
Show 26 quoted lines
> 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.

Show 27 quoted lines
> +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.
Show 5 quoted lines
>  showbranch.default::
>  	The default set of branches for linkgit:git-show-branch[1].
>  	See linkgit:git-show-branch[1].
> -- 
> 1.6.3.3
Yann Dirson· Jul 16, 2009, 21:20 UTC · re: Junio C Hamano · lore

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

On Sun, Jul 05, 2009 at 11:58:01PM -0700, Junio C Hamano wrote:
Show 17 quoted lines
> > +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 ?
Yann Dirson· Jul 22, 2009, 21:39 UTC · re: Yann Dirson · lore

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

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(-)
Yann Dirson· Jul 22, 2009, 21:39 UTC · re: Yann Dirson · lore

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

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(-)
Show changes to Documentation/config.txt +44 −0
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
Yann Dirson· Jul 22, 2009, 21:39 UTC · re: Yann Dirson · lore

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

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(-)
Show changes to 2 files +31 −12

Documentation/git-format-patch.txt, Documentation/git-send-email.txt

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
Markus Heidelberg· Jul 23, 2009, 05:31 UTC · re: Yann Dirson · lore

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

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.
Show 47 quoted lines
> 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

← back to recent threads