Size: 9801
Comment:
|
Size: 11110
Comment:
|
Deletions are marked like this. | Additions are marked like this. |
Line 2: | Line 2: |
Line 4: | 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/2008]]. |
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]]. |
Line 16: | Line 12: |
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 | The current code can be found [[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 19: | Line 15: |
Line 28: | Line 25: |
hg rebase [--source REV | --base REV] [--dest REV] [--collapse] [--detach] [--keep] [--keepbranches] | [--continue] | [--abort] }}} |
hg rebase [--source REV | --base REV] [--dest REV] [--collapse] [--detach] [--keep] [--keepbranches] | [--continue] | [--abort] }}} |
Line 32: | Line 28: |
Line 34: | Line 29: |
allows to specify a revision that will be rebased onto dest with all its descendants | . allows to specify a revision that will be rebased onto dest with all its descendants |
Line 37: | Line 32: |
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'' |
. 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'' |
Line 41: | Line 36: |
the destination onto which the required revisions will be rebased | . the destination onto which the required revisions will be rebased |
Line 44: | Line 39: |
resume an interrupted rebase | . resume an interrupted rebase |
Line 47: | Line 42: |
abort an interrupted rebase | . abort an interrupted rebase |
Line 50: | Line 45: |
collapse the rebased revisions | . collapse the rebased revisions |
Line 53: | Line 48: |
keep original revisions | . keep original revisions |
Line 56: | Line 51: |
keep original branch names | . keep original branch names |
Line 59: | Line 54: |
force detaching of source from its original branch | . force detaching of source from its original branch |
Line 63: | Line 58: |
{{{ hg pull --rebase }}} that pulls and rebases the local revisions if there's something to rebase. Otherwise it behaves like hg pull --update. |
{{{ hg pull --rebase }}} that pulls and rebases the local revisions if there's something to rebase. Otherwise it behaves like hg pull --update. |
Line 83: | Line 78: |
Line 87: | Line 81: |
hg pull }}} |
hg pull }}} |
Line 101: | Line 94: |
Line 105: | Line 97: |
hg rebase }}} |
hg rebase }}} |
Line 118: | Line 109: |
L1 [label="L1''"]; L2 [label="L2''"]; } }}} |
L1 [label="L1 '"]; L2 [label="L2 '"]; } }}} '''Note:''' As stated above, this can be achieved in one step using '''''hg pull --rebase''''' |
Line 124: | 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 129: | Line 119: |
Line 136: | Line 127: |
$ hg rebase --abort }}} |
$ hg rebase --abort }}} |
Line 143: | Line 133: |
$ hg rebase --continue }}} |
$ hg rebase --continue }}} |
Line 148: | Line 137: |
Line 150: | Line 140: |
* the rebasing point (source) is a merge revision and both of its parents are external | In this case, you will need to use the [[TransplantExtension|transplant]]and [[MqExtension|strip]] commands. For example: {{{ hg up -r <targetrev> # Needed because the transplant -m option doesn't work hg transplant <source>:tip hg strip <source> }}} * the rebasing point (source) is a merge revision and both of its parents are external |
Line 153: | Line 150: |
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 193: | Line 188: |
Line 206: | Line 200: |
B [label="B''"]; C [label="C''"]; } }}} |
B [label="B '"]; C [label="C '"]; } }}} |
Line 221: | Line 214: |
B [label="B''"]; C [label="C''"]; } }}} |
B [label="B '"]; C [label="C '"]; } }}} |
Line 227: | Line 219: |
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 241: | Line 232: |
Line 254: | Line 244: |
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 270: | Line 260: |
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 289: | Line 279: |
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 311: | Line 300: |
G [label="G''"]; } }}} |
G [label="G '"]; } }}} |
Line 317: | Line 305: |
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 329: | Line 332: |
}}} | }}} |
Line 340: | Line 342: |
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 352: | Line 379: |
e.g., P1',,N,, identifies the rebased first parent of '''N''' | e.g., P1',,N,, identifies the rebased first parent of '''N''' |
Line 355: | Line 382: |
|| |||| '''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 367: | Line 393: |
* 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. |
* 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. |
Line 378: | Line 399: |
Line 383: | Line 405: |
* [[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]] |
Line 385: | Line 407: |
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
The current code can be found 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
- 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
--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
In this case, you will need to use the transplantand strip commands. For example:
hg up -r <targetrev> # Needed because the transplant -m option doesn't work hg transplant <source>:tip hg strip <source>
- 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)