From: Philip Oakley Date: Sun, 19 May 2013 22:41:58 GMT Subject: Re: [RFC/PATCH 1/2] Doc rebase: Describe rebase as excluding merge commits Message-ID: <3E0A16E68BA845B5A1FFA22E066E59B1@PhilipOakley> In-Reply-To: <20130519180804.GE3362@elie.Belkin> From: "Jonathan Nieder" Sent: Sunday, May 19, 2013 7:08 PM > 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. Yes. > >> 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"? I was keeping the 'cryptic/esoteric' NAME line, because it is commented on in a few blogs [1]. It is accurate but let's not spoil those blogs... The fundamental reason for the update was to introduce 'somewhere' in the text the "excluding merge commits by default" note, and I couldn't find an easy way of updating the NAME line, and then realised a softer introduction wiould kill two birds with one stone. > > [...] >> --- 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 is specified, 'git rebase' will perform an automatic >> `git checkout ` 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 > ----------- > 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 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 . > 3. Checks out . ( 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 > to point to the new HEAD. > > The result is an updated 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? It's probably something I'd need help on (to ensure correctness). I'll have a go based on your suggestions in the next few days. > > Thanks, > Jonathan > -- [1] http://steveko.wordpress.com/2012/02/24/10-things-i-hate-about-git/ section 3 'update'.