Differences between revisions 1 and 27 (spanning 26 versions)

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 is being implemented as part of SummerOfCode.

Current implementation

The current code can be find [http://freehg.org/u/astratto/soc/ here]

Current version's features:

rebase both simple and complex cases
abort of an interrupted rebasing
resume of an interrupted rebasing
mq patches handling (TO CHECK)

Usage example

Let suppose we have the following repository:

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:

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

Scenarios

Now will be analyzed the most interesting scenarios.

Scenario A

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

In this scenario there are two interesting interactions:

rebase on top

rebase on an intermediate revision

Scenario B

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

rebase D on I

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

In this case two revisions (D and H) have been skipped.
rebase C on B

rebase G onto I

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.

D onto C

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)

-  ⇤ ← Revision 1 as of 2008-07-02 19:45:59 → 
  Size: 1957
  Editor: StefanoTortarolo
  Comment:
+   ← Revision 27 as of 2008-07-29 12:50:38 → ⇥
  Size: 7143
  Editor: StefanoTortarolo
  Comment: Add not valid situations
-Deletions are marked like this.
+Additions are marked like this.
 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 19:
+Line 21:
-== Usage examples ==
Let suppose we have the following repository
+ * mq patches handling (TO CHECK)

== Usage example ==
Let suppose we have the following repository:
-Line 34:
+Line 37:
-== Simple case ==
-Line 46:
+Line 48:
-  rankdir=LR
  node [shape=box]
  C1 -> C2 -> R1 -> R2 -> l1 -> l2
+    rankdir=LR;
    node [shape=box];

    C1 -> C2 -> R1 -> R2 -> R3;
    node [color=red];
    R3 -> L1 -> L2;
    L1 [label="L1`"];
    L2 [label="L2`"];
-Line 64:
+Line 71:
-{{{ hg rebase --abort }}}
+{{{
   $ hg rebase --abort 
}}}
-Line 69:
+Line 78:
-{{{ hg rebase --continue }}}
+{{{
   $ 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 

== 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 74:
+Line 294:
+----
CategoryNewFeatures

Diff for "RebaseProject"