Differences between revisions 38 and 39
Revision 38 as of 2013-08-26 23:42:49
Size: 13052
Editor: BrendanCully
Comment:
Revision 39 as of 2015-01-28 23:58:30
Size: 12008
Editor: mpm
Comment:
Deletions are marked like this. Additions are marked like this.
Line 10: Line 10:
When contributing to a project, sometimes there is the need to keep some patches private, while keeping the whole repository up-to-date.

In those cases it can be useful to "detach" the local changes, synchronize the repository with the mainstream and then append the private changes on top of the new remote changes. This operation is called ''rebase''.

In general, this extension allows to move revisions from a point to another, some common scenarios are shown in the section "Scenarios".

Rebase allows moving commits around in Mercurial's history (using a series of internal merges). This has many uses:

 * moving changesets between branches
 * "linearizing" history
 * reordering changesets
 * collapsing multiple changes into one changeset
Line 23: Line 25:
== Features ==
 * rebase both simple and complex cases
 * abort of an interrupted rebasing
 * resume of an interrupted rebasing
 * mq patches handling
 * detect changes during interruptions

== Usage ==
=== Synopsis ===
{{{
hg rebase [--source REV | --base REV] [--dest REV] [--collapse] [--keep] [--keepbranches] | [--continue] | [--abort]
}}}
=== Description ===
 * '''--source''' rev
  . allows to specify a revision that will be rebased onto dest with all its descendants

 * '''--base''' rev
  . the revision specified will be rebased along with its descendants and its ancestors up to the common point (excluded) between rev and dest's ancestors
  ''Note that this option conflicts with --source''

 * '''--dest''' rev
  . the destination onto which the required revisions will be rebased

 * '''--continue'''
  . resume an interrupted rebase

 * '''--abort'''
  . abort an interrupted rebase

 * '''--collapse'''
  . collapse the rebased revisions

 * '''--keep'''
  . keep original revisions

 * '''--keepbranches'''
  . keep original branch names

=== Integration with pull ===
Rebase provides an extra option for pull.

{{{
   hg pull --rebase
}}}
that pulls and rebases the local revisions if there's something to rebase. Otherwise it behaves like `hg pull --update`.

== A common case ==
It's important to notice that this extension can be invoked with no arguments.

Semantically, invoking plain rebase can be intended as ''take the branch I'm working on and make it current'', in other words this means moving the local changes onto the most recent head of the checked out named branch.

Let's imagine this situation:

== Basic usage ==

Let's imagine our repository looks like this:
Line 80: Line 34:
  C1 -> C2 -> L1 -> L2
}
}}}
L* represent our local changes after our last pull.

{{{
hg pull
}}}
pulls from mainstream two new revisions:
  0 -> B -> C -> D -> E
  C -> X -> Y -> Z

}
}}}

Here we have local commits X through Z diverging from the upstream line of history A through E. We can easily "linearize" the history by running:

{{{
$ hg rebase -s X -d E
}}}

This command will take commit from the source X ''and all its descendants'' and "move" them to descend instead from the destination E:
Line 94: Line 52:
  C1 -> C2 -> L1 -> L2
  node [color=green];
  C2 -> R1 -> R2
}
}}}
Usually what we would like to do is move L* onto R2 and this can be easily achieved with:

{{{
hg rebase
}}}
Result:

{{{#!dot
digraph {
    rankdir=LR;
    node [shape=box];

    C1 -> C2 -> R1 -> R2;
    node [color=red];
    R2 -> L1 -> L2;
    L1 [label="L1 '"];
    L2 [label="L2 '"];
}
}}}
'''Note:''' As stated above, this can be achieved in one step using '''''hg pull --rebase'''''
  A -> B -> C -> D -> E -> X2 -> Y2 -> Z2
}
}}}

<!> Note: moving changesets changes their changeset hashes and revision numbers. Thus we've given our changesets updated names.

Now let's imagine we decided commit X2 was a mistake. We could fix this by moving Y2 to descend from E and then [[StripExtension|strip]] X2:

{{{
$ hg rebase -s Y2 -d E
}}}

{{{#!dot
digraph {
  rankdir=LR
  node [shape=box]
  A -> B -> C -> D -> E -> "X2"
  E -> "Y3" -> "Z3"
}
}}}

{{{
$ hg strip X2
}}}

{{{#!dot
digraph {
  rankdir=LR
  node [shape=box]
  A -> B -> C -> D -> E -> "Y3" -> "Z3"
}
}}}

Lastly, let's imagine Y'' and Z'' really ought to be one commit. We can "collapse" them thusly:

{{{
$ hg rebase -r Y2::Z2 -d E --collapse
}}}

{{{#!dot
digraph {
  rankdir=LR
  node [shape=box]
  A -> B -> C -> D -> E -> YZ
}
}}}

Just about any rearrangement of history is possible with a series of rebases. See [[HisteditExtension|histedit]] for a tool that helps automate some of the more common tasks.
Line 121: Line 102:
A situation could arise where some changes in L* conflict with some changes in R*. In these cases, the extension will stop, store the current status, and provide the user with the ability to solve the conflict on his own. A situation could arise where some changes we're rebasing conflict with some changes in the destination. In these cases, the extension will stop, store the current status, and provide the user with the ability to solve the conflict on his own.

Rebase Extension

This extension is distributed along with Mercurial releases

Author: Stefano Tortarolo

1. Introduction

Rebase allows moving commits around in Mercurial's history (using a series of internal merges). This has many uses:

  • moving changesets between branches
  • "linearizing" history
  • reordering changesets
  • collapsing multiple changes into one changeset

2. Configuration

Enable the extension in the configuration file (e.g. .hg/hgrc):

[extensions]
rebase =

3. Basic usage

Let's imagine our repository looks like this:

Here we have local commits X through Z diverging from the upstream line of history A through E. We can easily "linearize" the history by running:

$ hg rebase -s X -d E

This command will take commit from the source X and all its descendants and "move" them to descend instead from the destination E:

<!> Note: moving changesets changes their changeset hashes and revision numbers. Thus we've given our changesets updated names.

Now let's imagine we decided commit X2 was a mistake. We could fix this by moving Y2 to descend from E and then strip X2:

$ hg rebase -s Y2 -d E

$ hg strip X2

Lastly, let's imagine Y and Z really ought to be one commit. We can "collapse" them thusly:

$ hg rebase -r Y2::Z2 -d E --collapse

Just about any rearrangement of history is possible with a series of rebases. See histedit for a tool that helps automate some of the more common tasks.

4. Dealing with conflicting merges

A situation could arise where some changes we're rebasing conflict with some changes in the destination. In these cases, the extension will stop, store the current status, and provide the user with the ability to solve the conflict on his own.

In event of an interruption, users have two choices:

  • abort
  • continue

4.1. Abort

An interrupted process can be aborted, thus restoring the repository to its original state, with:

$ hg rebase --abort

4.2. Continue

The most common situation, however, is resuming an interrupted process and this can be done with:

$ hg rebase --continue

5. When rebase is not allowed

There are situations in which a rebasing process is not allowed:

  • the rebasing point (source) is an ancestor of target
  • the rebasing point (source) is a merge revision and both of its parents are external

6. Notes about MQ Patches

In the current implementation MQ patches are qfinished and qimported after being rebased. This adds an export-like header to each rebased patch. e.g.,

  • Original patch:
    Description P0
    
    diff --git a/f b/f
    etc...
  • Rebased patch:
    # HG changeset patch
    # User Stefano Tortarolo <stefano.tortarolo@gmail.com>
    # Date 1217929313 -7200
    # Node ID 92bd85e9196feac01fdf2eb2ce7275e9a575a730
    # Parent  6e55161e68b2062d629c05b89b0ea3424eec9a2f
    Description P0
    
    diff --git a/f b/f
    etc...

7. Scenarios

Now will be analyzed the most interesting scenarios.

7.1. Scenario A

The first one is the simplest one, a simple branch.

In this scenario there are two interesting interactions:

7.1.1. rebase on top

$ hg up C
$ hg rebase --dest E

Another syntax that would yield the same result is:

$ hg rebase --dest E --base C

7.1.2. rebase on an intermediate revision

$ hg up C
$ hg rebase -d D

7.2. Scenario B

The second scenario involves something more complicated. In this scenario the user cloned from upstream, then merged several times.

7.2.1. rebase D on I

$ hg rebase --dest I --source D

  • Despite being a merge revision D hasn't been skipped in this case, as opposite to H.

7.2.2. rebase B on I

$ hg rebase --dest I --source B

  • In this case two revisions (D and H) have been skipped.

7.2.3. rebase C on B

$ hg rebase --dest B --source C

7.2.4. rebase G onto I

$ hg rebase --dest I --source G

Note: Prior Mercurial 2.3 you need to had --detach option in this situation. otherwise you get this result

7.3. Scenario C

This case represents a quite common situation, a repository with just one (merge) head.

7.3.1. D onto C

$ hg rebase --dest C --source D

  • Obviously the revision F has been skipped.

7.4. Collapsing

Sometimes it could be useful to be able to rebase changesets onto another branch, obtaining though just one revision.

This can be achieved using the option --collapse.

$ hg rebase --dest B --source C --collapse

or

The base option could have been used here too

$ hg rebase --dest B --base E --collapse

7.4.1. C onto B and collapsing

8. Details

8.1. Parent relationships

Rebase tries to turn <dest> into a parent of <root> while preserving the number of parents of rebased changesets:

  • A changeset with a single parent will always be rebased as a
    • changeset with a single parent.
  • A merge will be rebased as merge unless its parents are both
    • ancestors of <dest> or are themselves in the rebased set and pruned while rebased.

If one parent of <root> is an ancestor of <dest>, the rebased version of this parent will be <dest>. This is always true with --base option.

Otherwise, we need to replace the original parents with <dest>. This detaches the rebased set from its former location and rebases it onto <dest>. Changes introduced by ancestors of <root> not common with <dest> are removed from the rebased changesets.

  • If <root> has a single parent, set it to <dest>.

  • If <root> is a merge, we cannot decide which parent to

    • replace, the rebase operation is not clearly defined. This kind of rebase is not allowed.

The table below sums up this behavior:

one parent

merge

parent in ::<dest>

new parent is <dest>

parents in ::<dest> are remapped to <dest>

unrelated source

new parent is <dest>

ambiguous, abort

9. Command documentation

As of Mercurial 2.4, here is the official documentation of the rebase command.

    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.

    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.

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

    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.

    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.

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

    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.


CategoryBundledExtension

日本語

RebaseExtension (last edited 2017-03-28 19:44:56 by SietseBrouwer)