Re: [RFC/PATCH 1/2] Doc rebase: Describe rebase as excluding merge commits

> 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.

>
>> Include a softer paraphrased version from the crytic, well-loved,
>> but sometimes parodied, Name description, and tell users that merge
>> commits are excluded by default.
>
> I don't really follow this paragraph.  Are you saying "The NAME line
> is cryptic, but let's copy it anyway, since it is better than 
> nothing"?

>
> [...]
>> --- a/Documentation/git-rebase.txt
>> +++ b/Documentation/git-rebase.txt
>> @@ -16,6 +16,10 @@ SYNOPSIS
>>
>>  DESCRIPTION
>>  -----------
>> +'git rebase' will transfer local commits, excluding merge commits
>> +by default, to the head of the branch's upstream, or onto a new base
>> +if given.
>> +
>
> Not about this patch, but some day it would be nice to standardize on
> one tense for the DESCRIPTION sections of manpages.  Some git commands
> use the imperative ("Reply local commits, excluding merge commits, on
> top of ..."), some use the present indicative ("Replays local commits,
> excluding merge commits, ..."), and some use the future ("Will replay
> local commits, excluding merge commits, ...").
>
> The traditional tense for Unix manpages is the present indicative.
> But you are right to match the rest of the description here.
>
>>  If <branch> is specified, 'git rebase' will perform an automatic
>>  `git checkout <branch>` before doing anything else.  Otherwise
>>  it remains on the current branch.
>
> The description has become very long by now.  I wonder if it's
> possible to break it into chunks, like so?
>
> 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").>
>
> It proceeds using the following steps:
>
> 1. If <branch> is specified, ...
> 2. Decides which commits will need to be applied.
>     These are plain, non-merge commits that are ancestors of HEAD but
>     not of <upstream>.
> 3. Checks out <upstream>.  (<Explanation that technically it
>     detaches HEAD at this step.>)
> 4. Reapplies the commits listed on step (2), one by one, in order.
>     If merge failures are encountered, the program will exit and allow
>     the user to resolve them and resume or cancel the rebase.  See
>     the RESPONDING TO MERGE CONFLICTS section below for details.
> 5. Once all of the commits from step (2) have been applied, updates
>     <branch> to point to the new HEAD.
>
> The result is an updated <branch> that ...
>
> OPTIONS
> -------
> ...
>
> EXAMPLES
> --------
> Assume the following history exists and the current branch is "topic":
> ...
>
> Description of specific options like "--preserve-merges" and "--onto"
> could move out of the DESCRIPTION section and to the OPTIONS section.
>
> What do you think?