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

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