Re: worth enhancing "man git-rebase" to show non-HEAD examples?

[Junio C Hamano <gitster@pobox.com>]

"Robert P. J. Day" <rpjday@crashcourse.ca> writes:

>   one of the things i've noticed about the examples in "man
> git-rebase" is that they invariably show rebasing relative to a
> branch point that has not moved. for example, there's this example:
>
>        o---o---o---o---o  master
>             \
>              o---o---o---o---o  next
>                               \
>                                o---o---o  topic
>
> with subsequent sample command:
>
>   $ git rebase --onto master next topic
>
> sure, that works, but there seem to be no examples that show that this
> is a valid starting point as well:
>
>
>        o---o---o---o---o  master
>             \
>              o---o---o---o---o  next
>                       \
>                        o---o---o  topic

You mean that the 'topic' forked from 'next', and it is OK for 'next'
to acquire further commits since 'topic' forked from it, for you to
rebase 'topic' on another history?

The very first example in Documentation/git-rebase.txt shows a
3-commit topic A-B-C, forked from the master branch at E in 4-commit
D-E-F-G sequence, gets rebased.  Those F and G are in the same place
as those rightmost two commits you have on 'next' in the above
picture.

> as in, the examples in that man page could potentially suggest to an
> inexperienced reader that the *only* valid situations are rebasing as
> long as the other branch has not developed any further. (yes, i
> realize that, if you read carefully, it *should* make it clear, but i
> think it would be helpful to at least graphically show that
> happening.)
>
>   thoughts?

So, we have both pictures, and I do not see there is much to add.

By the way, I sense a mis-perception that led you to say "... has
not developed any further".  In the topology in your second
illustration, there is nothing to say that the rightmost two commits
on the 'next' branch were created _after_ topic has forked from
'next'.  It is not just possible but also often is sensible to fork
a topic closer to what it needs to build on top of, limiting its
dependency as small as possible, so the 'topic' could have been
forked from the middle of 'next' branch when it was originally
created.