Updating rebase help

Pierre-Yves David pierre-yves.david at logilab.fr
Wed Jan 30 07:10:26 CST 2013


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


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

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

2) change the usecase example

  - move it in a verbose section.
  - add an graphical example of the effect on the graph
  - add another example about reordering changesets.
  - (maybe) move it at another point of the help


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

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

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

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

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

> If a rebase is interrupted to manually resolve a merge, it can be
> continued with --continue/-c or aborted with --abort/-a.
> 
> Returns 0 on success, 1 if nothing to rebase.
-- 
Pierre-Yves David

http://www.logilab.fr/

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 198 bytes
Desc: Digital signature
URL: <http://selenic.com/pipermail/mercurial-devel/attachments/20130130/d516de2b/attachment.pgp>


More information about the Mercurial-devel mailing list