|
Size: 4878
Comment: Add section "Scenarios"
|
Size: 2597
Comment: move to RebaseExtension
|
| 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. |
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 5: |
| 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: | Line 7: |
| This feature is being implemented as part of SummerOfCode. | 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 13: | Line 12: |
| The current code can be find [http://freehg.org/u/astratto/soc/ here] | 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 16: | Line 15: |
| Line 20: | Line 20: |
| * detect changes during interruptions | |
| Line 21: | Line 22: |
| == Usage examples == Let suppose we have the following repository |
== 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 |
| Line 24: | Line 31: |
| {{{#!dot digraph { rankdir=LR node [shape=box] C1 -> C2 -> R1 -> R2 C2 -> L1 -> L2 } }}} |
* '''--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'' |
| Line 33: | Line 35: |
| where C* are common revisions, R* changes in upstream and L* local changes. | * '''--dest''' rev . the destination onto which the required revisions will be rebased |
| Line 35: | Line 38: |
| == Simple case == We want to rebase L* on top of R2. |
* '''--continue''' . resume an interrupted rebase |
| Line 38: | Line 41: |
| This can be achieved using: {{{ $ hg rebase L1 R2 }}} |
* '''--abort''' . abort an interrupted rebase |
| Line 43: | Line 44: |
| Result: | * '''--collapse''' . collapse the rebased revisions |
| Line 45: | Line 47: |
| {{{#!dot digraph { rankdir=LR; node [shape=box]; |
* '''--keep''' . keep original revisions |
| Line 50: | Line 50: |
| C1 -> C2 -> R1 -> R2 -> R3; node [color=red]; R3 -> L1 -> L2; L1 [label="L1`"]; L2 [label="L2`"]; } }}} |
* '''--keepbranches''' . keep original branch names |
| Line 58: | Line 53: |
| == Rebasing merged revisions == This is a common situation, in which we have cloned a repository and then merged with it. |
* '''--detach''' '''''(development version only)''''' . force detaching of source from its original branch |
| Line 61: | Line 56: |
| {{{#!dot digraph { rankdir=LR; center=true; node [shape=box]; C1 -> C2 -> R1 -> R2; C1 -> L1 -> L2; C2 -> L2; } }}} In this case the expected result of rebasing L2 on top of R2 is: {{{#!dot digraph { rankdir=LR; center=true; node [shape=box]; C1 -> C2 -> R1 -> R2; C1 -> L1; node [color=red]; R2 -> L2; L2 [label="L2`"]; } }}} But if we tried to rebase starting from L1, then ''rebase'' would recognize that L2 is an empty revision and it would skip it. {{{#!dot digraph G { rankdir=LR; center=true; node [shape=box]; C1 -> C2 -> R1 -> R2; node [color=red]; R2 -> L1; L1 [label="L1`"]; } }}} == 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: |
=== Integration with pull === Rebase provides an extra option for pull. |
| Line 117: | Line 60: |
| $ hg rebase --abort | hg pull --rebase |
| Line 119: | Line 62: |
| that pulls and rebases the local revisions if there's something to rebase. Otherwise it behaves like hg pull --update. | |
| Line 120: | Line 64: |
| === 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 fontname=Courier]; 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 G on I {{{#!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`"]; } }}} In this case the revision H has been skipped, because it would have been an empty revision. * 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; D [label="D`"]; G [label="G`"]; } }}} Despite being a merge revision D hasn't been skipped in this case. * 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`"]; } }}} |
|
| Line 243: | Line 67: |
| * [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 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.