From: Philip Oakley <philipoakley@iee.org>
Date: Mon, 20 May 2013 21:55:21 GMT
Subject: Re: [RFC/PATCH 1/2] Doc rebase: Describe rebase as excluding merge commits
Message-ID: <2F59222ECBA14673815BF42E6A7CE5A5@PhilipOakley>
In-Reply-To: <7v1u92xnuw.fsf@alter.siamese.dyndns.org>

From: "Junio C Hamano" <gitster@pobox.com>
Sent: Monday, May 20, 2013 5:43 AM
> Jonathan Nieder <jrnieder@gmail.com> writes:
>
>> Philip Oakley wrote:
>>
>>> Describe rebase in the description section.
>>
>> It already does that. :)  I think you mean "start with a summary",
>> which is a valuable improvement.
>
> It indeed is a good idea to give the "high-level introduction" at
> the very beginning, but I do not think it should describe only one
> of the three major modes of "git rebase" (i.e. no -m, no -i), like
> the proposed patch text does.  We should instead say what it is used
> for and why the user would want to use it that is common across
> these modes at a very high level.

That would repeat the NAME issue (of trying too hard to be exact & 
precise). This introductory text is that "summary". The patch 2/2 should 
be the one for the extra detail of the various whys and wherefores - at 
least that was my intent.

>
>> DESCRIPTION
>> -----------
>> <brief description of the purpose of the command, including some 
>> token
>> mention of *why* a user would want to use it (e.g., "so that the 
>> patches
>> apply cleanly to their new base").>
>
> Exactly.
> --