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 32 as of 2008-08-10 21:18:30 → 
  Size: 9273
  Editor: MartinGeisler
  Comment: Changed ` (grave accent) to ' (prime) by doubling the single quotes
+   ← 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://www.bitbucket.org/astratto/rebase-soc/ here] ([http://freehg.org/u/astratto/soc/ old repository])
+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 24:
+Line 25:
-== Usage ==
=== Synopsis ===
{{{
   hg rebase [--source rev | --base rev] [--dest rev] | [--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  

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

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

L* represent our local changes after our last pull.

{{{
   hg pull
}}}

pulls from mainstream two new revisions:

{{{#!dot
digraph {
  rankdir=LR
  node [shape=box]
  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''"];
}
}}}

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

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

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

 * rebase G onto I

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

'''Note:''' Rebase drops a parent relationship '''only''' if the parent is an ancestor of target.

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

== Details ==
=== Parent relationships ===
When rebasing a given node ('''N''') different situations may happen, depending on the status of its parent(s).

From now on P1,,N,, is used to refer to the first parent of '''N''', P2,,N,, to the second one.

e.g., P1',,N,, identifies the rebased first parent of '''N''' 

These situations are summed up in the following table:

||                     ||||       '''P2,,N,, = A'''   ||||        '''P2,,N,, = S'''       ||||         '''P2,,N,, = E'''     ||||     '''P2,,N,, = N'''     ||
|| '''P1,,N,, = A''' ||||                             |||| p1 = P2',,N,,                  |||| p1 = target, p2 = P2,,N,,     |||| p1 = target                 ||
|| '''P1,,N,, = S''' |||| p1 = P1',,N,,             |||| p1 = P1',,N,,, p2 = P2',,N,, |||| p1 = P1',,N,,, p2 = P2,,N,, |||| p1 = P1',,N,,             ||
|| '''P1,,N,, = E''' |||| p1 = target, p2 = P1,,N,, |||| p1 = P2',,N,,, p2 = P1,,N,,  ||||                                 |||| p1 = target, p2 = P1,,N,, ||

A: In ancestors(target)
S: In the rebasing series
E: External
N: None

The empty cells cover the cases in which:
 * P1,,N,, = P2,,N,, = A
 
 that means that also '''N''' is in ancestors(target) and this scenario is disallowed
 
 * P1,,N,, = P2,,N,, = E
 
 that means that '''N''' is a merged revision and none of its parents is ancestor of target.
 This scenario is disallowed (Idea: Can we make assumptions about a better revision point?)
 Note that this case can happen only if '''N''' is the rebasing point.

Also note that:
 * P1,,N,, = None entails that P2,,N,, = None
 * P1,,N,, = P2,,N,, = None is true only if '''N''' is root (this scenario is disallowed by the rule that a node can't be rebased onto a descendant)
-Line 370:
+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 372:
+Line 32:
-CategoryNewFeatures

Diff for "RebaseProject"

Rebase Project

Introduction

Current implementation

Related links