Workflows, rebase, patch theory

[Ben Finney]

Andrew Bennetts <andrew at canonical.com> writes:

> Ben Finney wrote:
> > For someone who was introduced to DVCS via GNU Arch -> baz -> bzr,
> > and who hasn't used git, all this talk of "rebase" is foreign. (It
> > also doesn't help that the Debian package 'bzr-rebase' has a
> > description that assumes the reader already knows what "rebase"
> > means.)
> 
> Have you seen the description at <http://bazaar-vcs.org/Rebase>?

I had, but have now re-read it.

> (Which is the same text that "bzr help rebase" gives with the plugin
> installed, I believe.)

It seems that the Debian package description for 'bzr-rebase' takes
the first paragraph from that page verbatim. Unfortunately that single
paragraph is utterly opaque without knowing what "rebase" is intended
to mean.

Fortunately, the *rest* of the page then goes on to explain. A couple
of questions arise.

    "The first step identifies the revisions that are in the current
    branch that are not in the parent branch. The current branch is
    then set to be at the same revision as the target branch, and each
    revision is replayed on top of the branch."

There seems to be a step missing here. After the "revisions that are
in the current branch that are not in the parent branch" are
identified, what happens to them? Presumably they're moved aside or
something, since it wouldn't make sense to later replay them
otherwise. When?

    "Once you have resolved all the conflicts you should run 'bzr
    rebase-continue' to continue the rebase operation.

    If conflicts are encountered and you decide that you do not wish
    to continue you can run 'bzr rebase-abort'."

This seems like a gaping hole in the process. What state can I expect
my branch to be in if I resolve the conflicts, but do neither of
'rebase-continue' nor 'rebase-abort'?

> To "rebase" is to take a series of changesets (from an existing
> series of revisions), and generate a new series of revisions against
> some designated base revision, one new revision per original
> revision. Commit messages are preserved.
> 
> So say you have:
> 
> A -> B -> C -> D
>  \
>   -> E -> F -> G
> 
> You could use rebase to generate:
> 
> A -> B -> C -> D
>                 \
>                  -> E' -> F' -> G'

This diagram, though used in several places where I've seen "rebase"
discussed, does not appear on the above page. It seems quite important
to the concept, so should be there IMAO.

> (Heh, I just noticed this essentially the same example as used in
> http://git.or.cz/gitwiki/GitFaq#head-1168c3027a2b7060df8c5cf141756c8e0e33139c)

It also seems quite essential to communicate that the above revisions
{E, F, G} are *gone*, and replaced by *different* revisions {E', F',
G'}. The current description doesn't give me that impression.

Thanks to everyone so far for the explanations.