format-patch / send-mail thrading documentation
cover format-patch / send-mail thrading documentation
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.
--- Documentation/config.txt | 40 ++++++++++++++++++++++++++++++++++++++++ 1 files changed, 40 insertions(+), 0 deletions(-)
Documentation/config.txt +40 -0
@@ -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].
Signature · 1 line
1.6.3.3
Re: [PATCH 1/2] List send-email config options in config.txt.
Quoted 16 lines · Yann Dirson
Signed-off-by Yann Dirson <[email protected]>--- Documentation/config.txt | 40 ++++++++++++++++++++++++++++++++++++++++ 1 files changed, 40 insertions(+), 0 deletions(-)Documentation/config.txt +3
-0@@ -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'.
Documentation/config.txt rerere.enabled:: · line 1394
Quoted 10 lines
Documentation/config.txt +10
-0+ +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.
Quoted 17 lines
Documentation/config.txt +17
-0+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::
Documentation/config.txt rerere.enabled:: · line 1421
Quoted 10 lines
Documentation/config.txt +10
-0+sendemail.smtppass:: +sendemail.suppresscc:: +sendemail.suppressfrom:: +sendemail.to:: +sendemail.smtpserver:: +sendemail.smtpserverport:: +sendemail.smtpuser:: +sendemail.thread:: +sendemail.validate:: +
Likewise.
Quoted 5 lines
Documentation/config.txt +0
-0showbranch.default:: The default set of branches for linkgit:git-show-branch[1]. See linkgit:git-show-branch[1].Signature · 1 line
1.6.3.3
PATCH 2/2 Improve doc for format-patch threading options.
In reply to Yann DirsonIt was not immediately clear to me that not specifying any threading at all would result in a deep-threading because of send-email.
--- Documentation/git-format-patch.txt | 15 +++++++++++---- Documentation/git-send-email.txt | 16 +++++++++++----- 2 files changed, 22 insertions(+), 9 deletions(-)
Documentation/git-format-patch.txt +11 -4
@@ -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
Documentation/git-send-email.txt +11 -5
@@ -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
Signature · 1 line
1.6.3.3
Re: [PATCH 2/2] Improve doc for format-patch threading options.
Yann Dirson, 06.07.2009:
Quoted 14 lines
Documentation/git-format-patch.txt +1
-1@@ -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]
Documentation/git-format-patch.txt include::diff-options.txt[] · line 127
Quoted 4 lines
Documentation/git-format-patch.txt +1
-0@@ -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.
Quoted 9 lines
Documentation/git-format-patch.txt +0
-2Add 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`
Documentation/git-format-patch.txt The optional <style> argument can be either `shallow` or `deep`. · line 144
Quoted 10 lines
Documentation/git-format-patch.txt +9
-1-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
Quoted 5 lines
Documentation/git-send-email.txt +0
-0
Documentation/git-send-email.txt specified, as well as 'body' if --no-signed-off-cc is specified. · line 216
Quoted 10 lines
Documentation/git-send-email.txt +2
-5@@ -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?
Quoted 12 lines
Documentation/git-send-email.txt +9
-0+ 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.
In reply to Yann DirsonYann Dirson, 06.07.2009:
Quoted 7 lines
+++
b/Documentation/git-format-patch.txtDocumentation/git-format-patch.txt +0
-2@@ -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`
Documentation/git-format-patch.txt The optional <style> argument can be either `shallow` or `deep`. · line 144
Quoted 10 lines
Documentation/git-format-patch.txt +9
-1-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 1/2] List send-email config options in config.txt.
In reply to Junio C HamanoQuoted 9 lines · Junio C Hamano
Quoted 9 lines
Documentation/config.txt +9
-0+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::
Quoted 8 lines
Documentation/config.txt rerere.enabled:: · line 1394
Quoted 4 lines
Documentation/config.txt +4
-0+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 ?
Re: [PATCH 2/2] Improve doc for format-patch threading options.
In reply to Markus HeidelbergQuoted 22 lines · Markus Heidelberg
Yann Dirson, 06.07.2009:
Quoted 7 lines
+++
b/Documentation/git-format-patch.txtDocumentation/git-format-patch.txt +0
-2@@ -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`Documentation/git-format-patch.txt The optional <style> argument can be either `shallow` or `deep`. · line 144
Quoted 10 lines
Documentation/git-format-patch.txt +9
-1-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.
Quoted 7 lines
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.
Yann Dirson, 17.07.2009:
Quoted 35 lines · Markus Heidelberg
Quoted 22 lines
Yann Dirson, 06.07.2009:
Quoted 7 lines
+++
b/Documentation/git-format-patch.txtDocumentation/git-format-patch.txt +0
-2@@ -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`Documentation/git-format-patch.txt The optional <style> argument can be either `shallow` or `deep`. · line 144
Quoted 10 lines
Documentation/git-format-patch.txt +9
-1-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.
Quoted 7 lines
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:
Quoted 8 lines
- 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
Quoted 3 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.
Markus
Re: [PATCH 2/2] Improve doc for format-patch threading options.
Quoted 8 lines · Markus Heidelberg
Quoted 3 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.
Re: [PATCH 2/2] Improve doc for format-patch threading options.
Yann Dirson, 17.07.2009:
Quoted 5 lines · Markus Heidelberg
Quoted 4 lines
Quoted 3 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.
Quoted 7 lines
Quoted 4 lines
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.
Quoted 11 lines · Markus Heidelberg
Yann Dirson, 17.07.2009:
Quoted 10 lines · Markus Heidelberg
Quoted 8 lines
Quoted 3 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.
Quoted 4 lines
Quoted 2 lines
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 :)
v2 cover format-patch / send-mail threading documentation
In reply to Yann DirsonThis 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.
Also mention deprecated aliases that do not appear in the send-email manpage.
--- Documentation/config.txt | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 44 insertions(+), 0 deletions(-)
Documentation/config.txt +44 -0
@@ -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].
Signature · 1 line
1.6.4.rc1.12.g05859c
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.
--- Documentation/git-format-patch.txt | 22 +++++++++++++++------- Documentation/git-send-email.txt | 21 ++++++++++++++++----- 2 files changed, 31 insertions(+), 12 deletions(-)
Documentation/git-format-patch.txt +15 -7
@@ -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
Documentation/git-send-email.txt +16 -5
@@ -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
Signature · 1 line
1.6.4.rc1.12.g05859c
Re: [PATCH 2/2] Improve doc for format-patch threading options.
Yann Dirson, 22.07.2009:
Quoted 2 lines
This hopefully makes the relationship between threading options of format-patch and send-email easier to grasp.
Yes, it does.
Quoted 37 lines
Signed-off-by Yann Dirson <[email protected]>--- Documentation/git-format-patch.txt | 22 +++++++++++++++------- Documentation/git-send-email.txt | 21 ++++++++++++++++----- 2 files changed, 31 insertions(+), 12 deletions(-)Documentation/git-format-patch.txt +6
-5@@ -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
Documentation/git-format-patch.txt include::diff-options.txt[] · line 144
Quoted 10 lines
Documentation/git-format-patch.txt +8
-2-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.
Quoted 4 lines
Documentation/git-format-patch.txt +1
-0+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
In reply to Yann DirsonSounds reasonable from a cursory look.
Thanks, will queue.