Updating rebase help

Greg Ward greg at gerg.ca
Thu Jan 31 12:48:31 CST 2013


On 30 January 2013, Pierre-Yves David said:
> I'm going to update the rebase help to refer to the --rev option. But I think
> the help could use a more generic update.
> 
> Below is the current help with inlined comment about what I would do.
> 
> Discuss…
> 
> > move changeset (and descendants) to a different branch
> 
> We use "branch" here, people tend to confuse that with "named branch".
> We could use "different point of the history".

But the rebase help uses "branch" consistently with the glossary. Do
you intend to modify the official description in the glossary, too?

Hmmm: maybe "anonymous branch" would be clearer, e.g.

  move changeset (and descendants) to a different anonymous branch

Alternately, I liked Tim Delaney's suggestion:

  move changeset (and descendants) to a different parent

which is both concise and accurate. Nice.

> > Rebase uses repeated merging to graft changesets from one part of
> > history (the source) onto another (the destination). This can be
> > useful for linearizing *local* changes relative to a master
> > development tree.

We should probably stop using "graft" here, since it's now a command
with its own (different) meaning. I like "move".

> I would:
> 1) highlight that topology of rebased changeset are conserved
>    (graft and git's rebase does not)

Sure, if you can do so with a few words. The current help is wordy
enough already. (Mea culpa, as I wrote most of the current help text!)

> > You should not rebase changesets that have already been shared
> > with others. Doing so will force everybody else to perform the
> > same rebase or they will end up with duplicated changesets after
> > pulling in your rebased changesets.
> 
> I would:
> - Move this in a .. note: section
> - make it much shorter with a reference to "hg help phases"

Yeah, we don't need to emphasise this as much now that we have phases.

> 
> > If you don't specify a destination changeset (``-d/--dest``),
> > rebase uses the tipmost head of the current named branch as the
> > destination. (The destination changeset is not modified by
> > rebasing, but new changesets are added as its descendants.)
> 
> I will probably rephase that. current form is (1) how to specify destination
> and what's the default. (2) what does it do. A (1) What is rebase destination
> (2) what the default and how to specify a custom destination.

I cannot understand your commentary. Please rephrase, or just show us
the proposed new help text.

> > You can specify which changesets to rebase in two ways: as a
> > "source" changeset or as a "base" changeset. Both are shorthand
> > for a topologically related set of changesets (the "source
> > branch"). If you specify source (``-s/--source``), rebase will
> > rebase that changeset and all of its descendants onto dest. If you
> > specify base (``-b/--base``), rebase will select ancestors of base
> > back to but not including the common ancestor with dest. Thus,
> > ``-b`` is less precise but more convenient than ``-s``: you can
> > specify any changeset in the source branch, and rebase will select
> > the whole branch. If you specify neither ``-s`` nor ``-b``, rebase
> > uses the parent of the working directory as the base.
> 
> I'll change this paragraph to mention the --rev option. In addition I would:
> 
> 1) have outstanding sub paragraph for each possible switch
> 2) verbose section that show what's the effect of each option
> 3) refer to --rev as "an option for advanced usage" and put detailled --rev
>    documentation in a verbose section.

Sure, seems reasonable.

> > By default, rebase recreates the changesets in the source branch
> > as descendants of dest and then destroys the originals. Use
> > ``--keep`` to preserve the original source changesets. Some
> > changesets in the source branch (e.g. merges from the destination
> > branch) may be dropped if they no longer contribute any change.
> 
> s/destroys/discarded/ small semantical swift make it "correct" for both strip
> and obsolete case.

Sounds OK.

> > One result of the rules for selecting the destination changeset
> > and source branch is that, unlike ``merge``, rebase will do
> > nothing if you are at the latest (tipmost) head of a named branch
> > with two heads. You need to explicitly specify source and/or
> > destination (or ``update`` to the other head, if it's the head of
> > the intended source branch).
> 
> I find this paragraph confusing. Moving it in a verbose section in the --dest
> parameters ?

I find rebase's behaviour confusing. ;-) The fact that it is
inconsistent with merge is annoying and bites me about 50% of the
times I use rebase. But hey, if you can find a clearer way to explain
this, please do!

       Greg
-- 
Greg Ward                            http://www.gerg.ca
<greg at gerg.ca>                       @gergdotca


More information about the Mercurial-devel mailing list