From mboxrd@z Thu Jan  1 00:00:00 1970
From: Markus Heidelberg <markus.heidelberg@web.de>
Subject: Re: [PATCH 2/2] Improve doc for format-patch threading options.
Date: Mon, 6 Jul 2009 10:36:03 +0200
Message-ID: <200907061036.04129.markus.heidelberg@web.de>
References: <cover.1246834883.git.ydirson@altern.org> <112440b74f47290e55209b23d1bfc66ed2423297.1246834884.git.ydirson@altern.org> <9820c7a185de928cf693a21a68d8550afe36d354.1246834884.git.ydirson@altern.org>
Reply-To: markus.heidelberg@web.de
Mime-Version: 1.0
Content-Type: text/plain;
  charset="iso-8859-1"
Content-Transfer-Encoding: 7bit
Cc: git@vger.kernel.org
To: Yann Dirson <ydirson@altern.org>
X-From: git-owner@vger.kernel.org Mon Jul 06 10:36:12 2009
Return-path: <git-owner@vger.kernel.org>
Envelope-to: gcvg-git-2@gmane.org
Received: from vger.kernel.org ([209.132.176.167])
	by lo.gmane.org with esmtp (Exim 4.50)
	id 1MNjgJ-0002Se-Jv
	for gcvg-git-2@gmane.org; Mon, 06 Jul 2009 10:36:12 +0200
Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand
	id S1752918AbZGFIgB (ORCPT <rfc822;gcvg-git-2@m.gmane.org>);
	Mon, 6 Jul 2009 04:36:01 -0400
Received: (majordomo@vger.kernel.org) by vger.kernel.org id S1752845AbZGFIgA
	(ORCPT <rfc822;git-outgoing>); Mon, 6 Jul 2009 04:36:00 -0400
Received: from fmmailgate02.web.de ([217.72.192.227]:47158 "EHLO
	fmmailgate02.web.de" rhost-flags-OK-OK-OK-OK) by vger.kernel.org
	with ESMTP id S1751065AbZGFIf7 (ORCPT <rfc822;git@vger.kernel.org>);
	Mon, 6 Jul 2009 04:35:59 -0400
Received: from smtp05.web.de (fmsmtp05.dlan.cinetic.de [172.20.4.166])
	by fmmailgate02.web.de (Postfix) with ESMTP id 6FA8810764309;
	Mon,  6 Jul 2009 10:36:02 +0200 (CEST)
Received: from [89.59.90.27] (helo=.)
	by smtp05.web.de with asmtp (TLSv1:AES256-SHA:256)
	(WEB.DE 4.110 #277)
	id 1MNjgA-0001LE-00; Mon, 06 Jul 2009 10:36:02 +0200
User-Agent: KMail/1.9.9
In-Reply-To: <9820c7a185de928cf693a21a68d8550afe36d354.1246834884.git.ydirson@altern.org>
Jabber-ID: markus.heidelberg@web.de
Content-Disposition: inline
X-Sender: markus.heidelberg@web.de
X-Provags-ID: V01U2FsdGVkX19OMiVDNKnUlts4yvzU3gR71+cvq3PJMul6s0y9
	LJtWXBUp5gtubGPqzdT4M1su9K/cPNT8yZ31hq+/ok2EIAB75h
	FEhL6waoqeuD5UtgTGsw==
Sender: git-owner@vger.kernel.org
Precedence: bulk
List-ID: <git.vger.kernel.org>
X-Mailing-List: git@vger.kernel.org
Archived-At: <http://permalink.gmane.org/gmane.comp.version-control.git/122777>

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