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

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

[Robert P. J. Day]

  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

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?

rday

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                  http://crashcourse.ca/dokuwiki

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================

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

[Junio C Hamano]

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

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

[Robert P. J. Day]

On Tue, 5 Mar 2019, Junio C Hamano wrote:

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

  yes, i see your point.

rday

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                  http://crashcourse.ca/dokuwiki

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================