Rebase Project

Introduction

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

This feature has been implemented as part of SummerOfCode/2008.

Current implementation

This project is distributed along with Mercurial release 1.1 as RebaseExtension. The original project code can be found here.

Current version's features:

rebase both simple and complex cases
abort of an interrupted rebasing
resume of an interrupted rebasing
mq patches handling
detect changes during interruptions

-  ⇤ ← Revision 21 as of 2008-07-28 18:08:50 → 
  Size: 4893
  Editor: StefanoTortarolo
  Comment: Correct scenario B
+   ← Revision 48 as of 2012-10-25 20:45:08 → ⇥
  Size: 1243
  Editor: mpm
  Comment:
-Deletions are marked like this.
+Additions are marked like this.
 Line 1:
+<<Include(A:historic)>>
<<Include(A:dev)>>
-Line 3:
+Line 6:
-When contributing to a project, sometimes there is the need to keep some
patches private, while keeping the whole repository up-to-date.
+When contributing to a project, sometimes there is the need to keep some patches private, while keeping the whole repository up-to-date.
-Line 6:
+Line 8:
-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 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''.
 Line 10:
 In general, this extension allows to move revisions from a point to another, some common scenarios are shown in the section "Scenarios".
 Line 12:
-This feature is being implemented as part of SummerOfCode.
+This feature has been implemented as part of [[SummerOfCode/2008]].
 Line 15:
-The current code can be find [http://freehg.org/u/astratto/soc/ here]
+This project is distributed along with Mercurial release 1.1 as RebaseExtension. The original project code can be found [[http://www.bitbucket.org/astratto/rebase-soc/|here]].
 Line 18:
-Line 21:
+Line 22:
- * mq patches handling (TO CHECK)
+ * mq patches handling
 * detect changes during interruptions
-Line 23:
+Line 25:
-== Usage example ==
Let suppose we have the following repository:

{{{#!dot
digraph {
  rankdir=LR
  node [shape=box]
  C1 -> C2 -> R1 -> R2
  C2 -> L1 -> L2
}
}}}

where C* are common revisions, R* changes in upstream and L* local changes.

We want to rebase L* on top of R2.

This can be achieved using:
{{{
   $ hg rebase L1 R2
}}}

Result:

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

    C1 -> C2 -> R1 -> R2 -> R3;
    node [color=red];
    R3 -> L1 -> L2;
    L1 [label="L1`"];
    L2 [label="L2`"];
}
}}}

== Dealing with conflicting merges ==
Sometimes could happen that some changes in L* conflicts with some changes in R*.
In these cases the extension will stop, store the current status and let user the ability to solve 
the conflict on his own.

In event of 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
}}}

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

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

    A -> D -> E;
    node [color=red];
    E -> B -> C;
    B [label="B`"];
    C [label="C`"];
}
}}}

 * rebase on an intermediate revision

{{{#!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

{{{#!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

{{{#!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

{{{#!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`"];
}
}}}


'''Note:''' Rebase G onto I is not allowed, because that would mean compacting G and D into G'. Rebase would suggest to rebase starting from D.

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

{{{#!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.
-Line 237:
+Line 28:
- * [http://code.google.com/soc/2008/hg/appinfo.html?csaid=EC7D811E53CA98EF GSoC's Abstract ]
+ * [[http://code.google.com/soc/2008/hg/appinfo.html?csaid=EC7D811E53CA98EF|GSoC's Abstract]]
 * RebaseExtension
-Line 239:
+Line 32:
-CategoryNewFeatures

Diff for "RebaseProject"

Rebase Project

Introduction

Current implementation

Related links