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

[Markus Heidelberg <markus.heidelberg@web.de>]

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