Rebase documentation issues

[Masklinn]

On 2011-05-23, at 11:50 , J.S. van Bethlehem wrote:
> Another thing I noticed is that it seems that (at least at the documentation side) not much has been going on for quite some time (>1 yr) So maybe all of this is obsolete now, because it was superseded by another extension??
As far as I know that is not the case, it's just that the concept of rebasing is pretty simple (once you grasp it), so I'd expect there is not much to do once it's been implemented.

To understand rebasing, you first need some branching:

  A B
  | |
  | |
  | /
  |/
  +
  |

Here you have two "branches" A and B (branches, heads, what have you). Maybe B is a feature branch for A, or some complex bugfix branch, or whatever. Does not really matter.

Now to get B's changes back into A, you have to merge them:

  A
  |
  |\
  | \
  | | B
  | |
  | |
  | /
  |/
  +
  |

This *may* create two issues (whether it does depends on people's personal sensibilities, mainly):

1. Because B was branched from A "a long time ago", there may be merge conflicts which will have to be resolved by the one doing the merging. Or will have to result in some back and forth between the proposer and the merger. The person best-placed to resolve those conflicts is the writer of B. This can be done by merging A into B right before proposing a merge:

  A
  |
  |\
  | \
  | ,B
  ,'|
  | |
  | /
  |/
  +
  |

but that's kind-of disgusting. Furthermore, in any case, it requires resolving conflicts for all merged revisions at once, which may or may not be the easiest way.

2. Some people don't like seeing parallel developments, for some reason.


Anyway that's where rebase comes in: rebase will replay all commits from a branch (B) onto a different part of the source branch (A): it changes the *base* of the (B) branch.

Hence, the name.

The result of rebase on the original schema is:

    B
    |
    |
    /
  A/
  |
  |
  |
  |
  +
  |

(where "+" notes the original branching revision)

Rebase "lies" by making histories look linear and the writer of B will resolve any conflict (if there is one) stemming from replaying B on A, instead of the merger having to do so. The merger can either "pull" B, resulting in:

  A, B
  |
  |
  |
  |
  |
  |
  |
  |
  +
  |

or merge it, in order to get a single revision for B (and keep track that B was a separate branch at one point).

Oh, and rebase does not *move* branch B here, it deletes the old one and creates a new one instead (actually the other way around, so you can recover if there's a problem while rebasing).

That's pretty much it. I hope I didn't make things more confusing, if I did… I'm sorry