Differences between revisions 28 and 42 (spanning 14 versions)
⇤ ← Revision 28 as of 2008-08-05 09:52:00 →
Size: 7766
Editor: StefanoTortarolo
Comment: Add notes about mq patches handling
← Revision 42 as of 2010-03-01 21:40:13 → ⇥
Size: 10858
Editor: GregWard
Comment: formatting; grammar fix
Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
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.		 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/2008]].
Line 15: Line 12:
The current code can be find [http://freehg.org/u/astratto/soc/ here] The current code can be find [[http://www.bitbucket.org/astratto/rebase-soc/|here]] and [[http://www.selenic.com/hg/index.cgi/file/73268e317ad3/hgext/rebase.py#l1|here]] ([[http://freehg.org/u/astratto/soc/|old repository]]). This project is distributed along with Mercurial release 1.1 as RebaseExtension
Line 18: Line 15:
Line 22: Line 20:

== Usage example ==
Let suppose we have the following repository:		  * detect changes during interruptions

== Usage ==
=== Synopsis ===
{{{
hg rebase [--source REV | --base REV] [--dest REV] [--collapse] [--detach] [--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

 * '''--detach''' '''''(development version only)'''''
  . force detaching of source from its original branch

=== 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:
Line 30: Line 75:
  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
}}}
   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
}}}
Line 51: Line 106:
    C1 -> C2 -> R1 -> R2 -> R3;
    node [color=red];
    R3 -> L1 -> L2;
    L1 [label="L1`"];
    L2 [label="L2`"];
}
}}}		     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'''''
Line 60: Line 116:
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.		 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.
Line 65: Line 119:
Line 72: Line 127:
   $ hg rebase --abort 
}}}
 $ hg rebase --abort
}}}
Line 79: Line 133:
   $ hg rebase --continue
}}}
 $ hg rebase --continue
}}}
Line 84: Line 137:
Line 86: Line 140:
 * the rebasing point (source) is a merge revision and both of its parents are external   * the rebasing point (source) is a merge revision and both of its parents are external
Line 89: Line 143:
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...
   }}}

 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...
}}}
Line 129: Line 181:
Line 142: Line 193:
    B [label="B`"];
    C [label="C`"];
}
}}}
     B [label="B '"];
    C [label="C '"];
}
}}}
Line 157: Line 207:
    B [label="B`"];
    C [label="C`"];
}
}}}
     B [label="B '"];
    C [label="C '"];
}
}}}
Line 163: Line 212:
The second scenario involves something more complicated.
In this scenario the user cloned from upstream, then merged several times. 		 The second scenario involves something more complicated. In this scenario the user cloned from upstream, then merged several times.
Line 177: Line 225:
Line 190: Line 237:
    D [label="D`"];
    G [label="G`"];
}
}}}
 Despite being a merge revision D hasn't been '''skipped''' in this case, as opposite to H.		     D [label="D '"];
    G [label="G '"];
}
}}}
 . Despite being a merge revision D hasn't been '''skipped''' in this case, as opposite to H.
Line 206: Line 253:
    B [label="B`"];
    G [label="G`"];
}
}}}
 In this case two revisions (D and H) have been skipped. 		     B [label="B '"];
    G [label="G '"];
}
}}}
 . In this case two revisions (D and H) have been skipped.
Line 225: Line 272:
    C [label="C`"];
    E [label="E`"];
    F [label="F`"];
    I [label="I`"];
    G [label="G`"];
    H [label="H`"];
}
}}}
     C [label="C '"];
    E [label="E '"];
    F [label="F '"];
    I [label="I '"];
    G [label="G '"];
    H [label="H '"];
}
}}}
Line 247: Line 293:
    G [label="G`"];
}
}}}

'''Note:''' Rebase drops a parent relationship '''only''' if the parent is an ancestor of target.		     G [label="G '"];
}
}}}
'''Note:''' Rebase drops a parent relationship '''only''' if the parent is an ancestor of target.

Using a '''development version''' is available the new '''''--detach''''' option that drops this relationship.

{{{#!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 '"];
}
}}}
Line 265: Line 327:
}}}   }}}
Line 276: Line 337:
    D [label="D`"];
    E [label="E`"];
}
}}}
 Obviously the revision F has been skipped.		     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'''''.

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

 * 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 '"];
}
}}}
Line 288: Line 376:
e.g., P1',,N,, identifies the rebased first parent of '''N'''  e.g., P1',,N,, identifies the rebased first parent of '''N'''
Line 291: Line 379:

|| |||| '''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		 || ||||<style="text-align: center;">'''P2,,N,, = A''' ||||<style="text-align: center;">'''P2,,N,, = S''' ||||<style="text-align: center;">'''P2,,N,, = E''' ||||<style="text-align: center;">'''P2,,N,, = N''' ||
||'''P1,,N,, = A''' ||||<style="text-align: center;"> ||||<style="text-align: center;">p1 = P2',,N,, ||||<style="text-align: center;">p1 = target, p2 = P2,,N,, ||||<style="text-align: center;">p1 = target ||
||'''P1,,N,, = S''' ||||<style="text-align: center;">p1 = P1',,N,, ||||<style="text-align: center;">p1 = P1',,N,,, p2 = P2',,N,, ||||<style="text-align: center;">p1 = P1',,N,,, p2 = P2,,N,, ||||<style="text-align: center;">p1 = P1',,N,, ||
||'''P1,,N,, = E''' ||||<style="text-align: center;">p1 = target, p2 = P1,,N,, ||||<style="text-align: center;">p1 = P2',,N,,, p2 = P1,,N,, ||||<style="text-align: center;"> ||||<style="text-align: center;">p1 = target, p2 = P1,,N,, ||




A: In ancestors(target) S: In the rebasing series E: External N: None
Line 303: Line 390:
Line 304: Line 392:
 
Line 306: Line 393:
 
Line 308: Line 395:
   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.		  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.
Line 314: Line 398:
Line 319: Line 404:
 * [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

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/2008.

Current implementation

The current code can be find here and here (old repository). This project is distributed along with Mercurial release 1.1 as RebaseExtension

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

Usage

Synopsis

hg rebase [--source REV | --base REV] [--dest REV] [--collapse] [--detach] [--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

  • --detach (development version only)

    • force detaching of source from its original branch

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:

L* represent our local changes after our last pull. 

hg pull

pulls from mainstream two new revisions:

Usually what we would like to do is move L* onto R2 and this can be easily achieved with: 

hg rebase

Result:

Note: As stated above, this can be achieved in one step using hg pull --rebase

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.

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.

Using a development version is available the new --detach option that drops this relationship.

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.

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.

  • C onto B and collapsing

Details

Parent relationships

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

From now on P1N is used to refer to the first parent of N, P2N to the second one.

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

These situations are summed up in the following table:

P2N = A

P2N = S

P2N = E

P2N = N

P1N = A

p1 = P2'N

p1 = target, p2 = P2N

p1 = target

P1N = S

p1 = P1'N

p1 = P1'N, p2 = P2'N

p1 = P1'N, p2 = P2N

p1 = P1'N

P1N = E

p1 = target, p2 = P1N

p1 = P2'N, p2 = P1N

p1 = target, p2 = P1N

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

The empty cells cover the cases in which:

  • P1N = P2N = A that means that also N is in ancestors(target) and this scenario is disallowed

  • P1N = P2N = 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:

  • P1N = None entails that P2N = None

  • P1N = P2N = 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)

CategoryNewFeatures

RebaseProject (last edited 2012-10-25 20:45:08 by mpm)