Updating rebase help

[Augie Fackler]

On Wed, Jan 30, 2013 at 02:10:26PM +0100, Pierre-Yves David wrote:
> 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…
>

Happy to try and edit something if you want to make a CL and we can
pass it back and forth using evolve or some such.

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

+0, but I'd be +1 if someone can come up with a pithier way to express
"different point in 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.

Not sure I understand this point - isn't histedit the weapon of choice
for reordering changes?

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

Yeah, given that phases protects users from this we can probably hide
it.

>
[...]

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

I think we should only make that edit after obsolete is on all the time.

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



> _______________________________________________
> Mercurial-devel mailing list
> Mercurial-devel at selenic.com
> http://selenic.com/mailman/listinfo/mercurial-devel