#pragma section-numbers 2
= Rebase Extension =
'''This extension is distributed along with Mercurial releases'''

''Author: Stefano Tortarolo''

<<TableOfContents>>

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

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

{{{
[extensions]
rebase =
}}}

== Basic usage ==

Let's imagine our repository looks like this:

{{{#!dot
digraph {
  rankdir=LR
  node [shape=box]
  A -> 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:

{{{#!dot
digraph {
  rankdir=LR
  node [shape=box]
  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 Y3 and Z3 really ought to be one commit. We can "collapse" them thusly:

{{{
$ hg rebase -r Y3::Z3 -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.

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

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

{{{
$ hg rebase --abort
}}}
=== Continue ===
The most common situation, however, is resuming an interrupted process and this can be done with:

{{{
$ hg rebase --continue
}}}
== 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

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

== Scenarios ==
Now will be analyzed the most interesting scenarios.

=== Scenario A ===
The first one is the simplest one, a simple branch.

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

    A -> D -> E;
    A -> B -> C;
}
}}}
In this scenario there are two interesting interactions:

==== rebase on top ====
{{{
$ hg up C
$ hg rebase --dest E
}}}
{{{#!dot
digraph {
    node [shape=box];
    graph [rankdir=LR];

    A -> D -> E;
    node [color=red];
    E -> B -> C;
    B [label="B '"];
    C [label="C '"];
}
}}}
Another syntax that would yield the same result is:

{{{
$ hg rebase --dest E --base C
}}}
==== rebase on an intermediate revision ====
{{{
$ hg up C
$ hg rebase -d D
}}}
{{{#!dot
digraph {
    node [shape=box];
    graph [rankdir=LR];

    A -> D -> E;
    node [color=red];
    D -> B -> C;
    B [label="B '"];
    C [label="C '"];
}
}}}
=== Scenario B ===
The second scenario involves something more complicated. In this scenario the user cloned from upstream, then merged several times.

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

    A -> C -> E -> F -> I;
    A -> B -> D -> G -> H;
    C -> D;
    F -> H;
}
}}}
==== rebase D on I ====
{{{
$ hg rebase --dest I --source D
}}}
{{{#!dot
digraph {
    node [shape=box];
    graph [rankdir=LR];

    A -> C -> E -> F -> I;
    A -> B;
    node [color=red];
    I -> D -> G;
    B -> D;
    D [label="D '"];
    G [label="G '"];
}
}}}
 . Despite being a merge revision D hasn't been '''skipped''' in this case, as opposite to H.

==== rebase B on I ====
{{{
$ hg rebase --dest I --source B
}}}
{{{#!dot
digraph {
    node [shape=box];
    graph [rankdir=LR];

    A -> C -> E -> F -> I;
    node [color=red];
    I -> B -> G;
    B [label="B '"];
    G [label="G '"];
}
}}}
 . In this case two revisions (D and H) have been skipped.

==== rebase C on B ====
{{{
$ hg rebase --dest B --source C
}}}
{{{#!dot
digraph {
    node [shape=box];
    graph [rankdir=LR];

    A -> B;
    node [color=red];
    B -> C -> E -> F -> I;
    C -> G -> H;
    F -> H;

    C [label="C '"];
    E [label="E '"];
    F [label="F '"];
    I [label="I '"];
    G [label="G '"];
    H [label="H '"];
}
}}}
==== rebase G onto I ====
{{{
$ hg rebase --dest I --source G
}}}
{{{#!dot
digraph {
    node [shape=box];
    graph [rankdir=LR];

    A -> C -> E -> F -> I;
    A -> B -> D;
    C -> D;
    node [color=red];
    I -> G;
    G [label="G '"];
}
}}}
'''Note:''' Prior Mercurial 2.3 you need to had ''--detach'' option in this situation. otherwise you get this result

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

    A -> C -> E -> F -> I;
    A -> B -> D;
    C -> D;
    node [color=red];
    D -> G;
    I -> G;
    G [label="G '"];
}
}}}
=== Scenario C ===
This case represents a quite common situation, a repository with just one (merge) head.

{{{#!dot
digraph {
    node [shape=box];
    graph [rankdir=LR];
    A -> B -> C;
    A -> D -> E;
    C -> F;
    E -> F;
}
}}}
==== D onto C ====
{{{
$ hg rebase --dest C --source D
}}}
{{{#!dot
digraph {
    node [shape=box];
    graph [rankdir=LR];
    A -> B -> C;
    node [color=red];
    C -> D -> E;
    D [label="D '"];
    E [label="E '"];
}
}}}
 . Obviously the revision F has been skipped.

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

{{{#!dot
digraph {
    node [shape=box];
    graph [rankdir=LR];
    A -> B;
    A -> C -> D -> E;
}
}}}
The base option could have been used here too

{{{
$ hg rebase --dest B --base E --collapse
}}}
==== C onto B and collapsing ====
{{{#!dot
digraph {
    node [shape=box];
    graph [rankdir=LR];
    A -> B;
    node [color=red];
    B -> CDE;
    CDE [label="C ' + D ' + E '"];
}
}}}
== Details ==
=== 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 ||




== Command documentation ==
As of Mercurial 4.1, here is the official documentation of the rebase command.

{{{
move changeset (and descendants) to a different branch

    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.

    Published commits cannot be rebased (see 'hg help phases'). To copy
    commits, see 'hg help graft'.

    If you don't specify a destination changeset ("-d/--dest"), rebase will
    use the same logic as 'hg merge' to pick a destination.  if the current
    branch contains exactly one other head, the other head is merged with by
    default.  Otherwise, an explicit revision with which to merge with must be
    provided.  (destination changeset is not modified by rebasing, but new
    changesets are added as its descendants.)

    Here are the ways to select changesets:

      1. Explicitly select them using "--rev".
      2. Use "--source" to select a root changeset and include all of its
         descendants.
      3. Use "--base" to select a changeset; rebase will find ancestors and
         their descendants which are not also ancestors of the destination.
      4. If you do not specify any of "--rev", "source", or "--base", rebase
         will use "--base ." as above.

    Rebase will destroy original changesets unless you use "--keep". It will
    also move your bookmarks (even if you do).

    Some changesets may be dropped if they do not contribute changes (e.g.
    merges from the destination branch).

    Unlike "merge", rebase will do nothing if you are at the branch tip of a
    named branch with two heads. You will need to explicitly specify source
    and/or destination.

    If you need to use a tool to automate merge/conflict decisions, you can
    specify one with "--tool", see 'hg help merge-tools'. As a caveat: the
    tool will not be used to mediate when a file was deleted, there is no hook
    presently available for this.

    If a rebase is interrupted to manually resolve a conflict, it can be
    continued with --continue/-c or aborted with --abort/-a.

    Returns 0 on success, 1 if nothing to rebase or there are unresolved
    conflicts.
}}}
== Related links ==
 * RebaseProject
 * RebasePlan
 * [[http://code.google.com/soc/2008/hg/appinfo.html?csaid=EC7D811E53CA98EF|GSoC's Abstract]]
 * RebaseIfExtension - A separate (unbundled) extension that only rebases if there are no conflicted files, otherwise does a merge

----
CategoryBundledExtension

[[JapaneseRebaseExtension|日本語]]