Rebase Extension

This extension is distributed along with Mercurial releases

Author: Stefano Tortarolo

1. Configuration

Enable the extension in the configuration file (e.g. .hg/hgrc):

[extensions]
rebase = 

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

1. Features

Usage

1. Synopsis

   hg rebase [--source REV | --base REV] [--dest REV] [--collapse] [--detach] [--keep] [--keepbranches] | [--continue] | [--abort]

2. Description

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

A situation could arise where some changes in L* conflict with some changes in R*. In these cases, the extension will stop, store the current status, and provide the user with the ability to solve the conflict on his own.

In event of an interruption, users have two choices:

1. Abort

An interrupted process can be aborted, thus restoring the repository to its original state, with:

$ hg rebase --abort

2. 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:

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

Scenarios

Now will be analyzed the most interesting scenarios.

1. Scenario A

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

In this scenario there are two interesting interactions:

2. Scenario B

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

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.

3. Scenario C

This case represents a quite common situation, a repository with just one (merge) head.

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

Details

1. 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:

Also note that:


CategoryBundledExtension