git rebase command and docs questions

git rebase command and docs questions

[Eugene Sajine]

Hi,

I have few questions about rebase and its help content:

1. In case of this situation

o---o---o---o---o  master
        \
         o---o---o---o---o  next
                          \
                           o---o---o  topic


“git rebase master topic” says:
The current branch topic is up-to-date.

This message seems to be confusing and even incorrect.
The actual problem, as I understand, is that topic branch is not a
direct descendant of the master branch, therefore
“git rebase –onto master next topic” should be used instead.
Is there a way for git to identify this problem more correctly and
print more helpful error message?

2. The rebase help is a bit confusing in its “–onto” option part.
Initially help says that the form:

git rebase master topic

is a shorthand for git checkout topic, git rebase master

But, in “git rebase –onto master next topic” the meaning of the “next
topic” parameters is different: as I understand, it actually specifies
a range of commits from next to topic,  because –onto changes the way
the whole command is working, but it is not clarified in help. Is that
correct understanding?


3. The part of help from “Another example of --onto option is to
rebase part of a branch.” Is actually demonstrating absolutely the
same thing as the one before with the only difference that in the
second example the master has not advanced. There was probably some
different intention, but currently it looks like confusing
duplication.

Thanks,
Eugene

Re: git rebase command and docs questions

[Sverre Rabbelier]

Heya,

On Fri, Apr 9, 2010 at 20:49, Eugene Sajine <euguess@gmail.com> wrote:
> But, in “git rebase –onto master next topic” the meaning of the “next
> topic” parameters is different: as I understand, it actually specifies
> a range of commits from next to topic,  because –onto changes the way
> the whole command is working, but it is not clarified in help. Is that
> correct understanding?

I've never been able to remember how rebase --onto works, perhaps if
we actually let users specify a range it would be more intuitive?

$ git rebase next..topic master

-- 
Cheers,

Sverre Rabbelier

Re: git rebase command and docs questions

[Eugene Sajine]

On Fri, Apr 9, 2010 at 4:37 PM, Sverre Rabbelier <srabbelier@gmail.com> wrote:
> Heya,
>
> On Fri, Apr 9, 2010 at 20:49, Eugene Sajine <euguess@gmail.com> wrote:
>> But, in “git rebase –onto master next topic” the meaning of the “next
>> topic” parameters is different: as I understand, it actually specifies
>> a range of commits from next to topic,  because –onto changes the way
>> the whole command is working, but it is not clarified in help. Is that
>> correct understanding?
>
> I've never been able to remember how rebase --onto works, perhaps if
> we actually let users specify a range it would be more intuitive?
>
> $ git rebase next..topic master

I thought about it too. Even with the old syntax:

git rebase --onto master next..topic

at least as a second option the whole command would be much more
understandable for users. Currently, it fails with such range.

Thanks,
Eugene

Re: git rebase command and docs questions

[Junio C Hamano]

Sverre Rabbelier <srabbelier@gmail.com> writes:

> On Fri, Apr 9, 2010 at 20:49, Eugene Sajine <euguess@gmail.com> wrote:
>> But, in “git rebase –onto master next topic” the meaning of the “next
>> topic” parameters is different: as I understand, it actually specifies
>> a range of commits from next to topic,  because –onto changes the way
>> the whole command is working, but it is not clarified in help. Is that
>> correct understanding?
>
> I've never been able to remember how rebase --onto works, perhaps if
> we actually let users specify a range it would be more intuitive?
>
> $ git rebase next..topic master

Hmm, re*base* means "change the base to _this one_"; the above is more
like "replay these on master", which is often a useful operation but is
different.

Suppose other people have worked on the project and made their pushes
since you started working on your changes:

      o---o master
     /
 ---o---o---o---o origin

"git rebase origin" asks "I know my current work is based on a tad stale
state, and I'd prefer a linear history, so change the base to origin".

If the thing of whose base you want to change is not your "current work",
then you name that explicitly, i.e. "git rebase origin master" (i.e. the
second branch name defaults to HEAD as usual).

Onto is an optional feature that is primarily for correcting your earlier
mistakes.  Notice in the above picture, other people doing parallel work
and pushing their changes out is part of the normal life of distributed
development; there is no mistake on your part involved.

But suppose you started building bugfixes in a topic forked from origin,
but after that you realize they should be based on origin/maint:

                   X---Y fixes
                  /
         o---o---o---o---o origin
        /
    ---o---o---o origin/maint

You could have made fixes branch that houses X and Y on origin/maint (and
later merge that to master to be pushed to origin), but you did not have
perfect foresight.  You do not obviously want to change the base of whole
'fixes' branch to 'origin/maint', as that will pull in changes in origin
that are not related to your fixes.

You would want to rebase 'fixes' branch (whose fork point can be specified
with 'origin') but not on top of 'origin', but on 'origin/maint'.  Hence
instead of running "git rebase origin" to produce

                           X'--Y' fixes
                          /
         o---o---o---o---o origin
        /
    ---o---o---o origin/maint

You would say "git rebase --onto origin/maint origin" to transplant X' and
Y' as if you started working from 'origin/maint':


         o---o---o---o---o origin
        /
    ---o---o---o origin/maint
                \
                 X'--Y' fixes

If you _had_ your "replay" command, the workflow for this would be:

    $ git checkout -b maint-fixes origin/maint
    $ git replay origin..fixes


Before somebody else makes useless noises, "cherry-pick" could be a good
command in the existing UI set to do that kind of thing.

Re: git rebase command and docs questions

[Sverre Rabbelier]

Heya,

On Fri, Apr 9, 2010 at 23:11, Junio C Hamano <gitster@pobox.com> wrote:
> Hmm, re*base* means "change the base to _this one_"; the above is more
> like "replay these on master", which is often a useful operation but is
> different.

Yes, I guess that's true.

> If you _had_ your "replay" command, the workflow for this would be:
>
>    $ git checkout -b maint-fixes origin/maint
>    $ git replay origin..fixes

True again.

> Before somebody else makes useless noises, "cherry-pick" could be a good
> command in the existing UI set to do that kind of thing.

I still think the UI for --onto is awkward. At the very least it should be:

git rebase --fork-at=origin origin/maint fixes

Or something like that. Since currently you suddenly have to specify
an argument to --onto that was previously positional. Does that make
sense?

Case 1:
git rebase origin fixes
git rebase <new_base> <tip>

Case 2:
git rebase --onto origin/maint origin fixes
git rebase --onto=<new_base> <fork_point> <tip>

I know that in the --onto case <new_base> is not an argument to
--onto, but that's what it looks/feels like. Said differently, it's
just _really weird_ that a new argument (for a different mode) shows
up between two other arguments. It should either be at the beginning,
or at the end, but in the middle is just awkward, no?

So another solution might be to change the position of the
<fork_point> in the --onto case.

-- 
Cheers,

Sverre Rabbelier

Re: git rebase command and docs questions

[Eugene Sajine]

On Fri, Apr 9, 2010 at 5:23 PM, Sverre Rabbelier <srabbelier@gmail.com> wrote:
> Heya,
>
> On Fri, Apr 9, 2010 at 23:11, Junio C Hamano <gitster@pobox.com> wrote:
>> Hmm, re*base* means "change the base to _this one_"; the above is more
>> like "replay these on master", which is often a useful operation but is
>> different.
>
> Yes, I guess that's true.

I'm a bit confused. Isn't the rebase actually replaying the commits
one by one starting from new base instead of old one?
I believe it does apply diffs one by one, else there would be no
conflicts during rebase whatsoever.
Secondly, git complains about range not specified if you will try to
execute something like

git rebase --onto  master topic

when topic is not direct descendant of master.
Git will say "not a range".

So, That's why i make a conclusion that the real meaning of

git rebase --onto master next topic

is very close if not exactly matching the

git rebase --onto master next..topic

>
>> If you _had_ your "replay" command, the workflow for this would be:
>>
>>    $ git checkout -b maint-fixes origin/maint
>>    $ git replay origin..fixes
>
> True again.
>Yep therefore the interface
>
>> Before somebody else makes useless noises, "cherry-pick" could be a good
>> command in the existing UI set to do that kind of thing.
>
> I still think the UI for --onto is awkward. At the very least it should be:
>
> git rebase --fork-at=origin origin/maint fixes
>
> Or something like that. Since currently you suddenly have to specify
> an argument to --onto that was previously positional. Does that make
> sense?
>
> Case 1:
> git rebase origin fixes
> git rebase <new_base> <tip>
>
> Case 2:
> git rebase --onto origin/maint origin fixes
> git rebase --onto=<new_base> <fork_point> <tip>
>
> I know that in the --onto case <new_base> is not an argument to
> --onto, but that's what it looks/feels like.

How is that possible that it is not an argument to --onto???

from docs:

SYNOPSIS

git rebase [-i | --interactive] [options] [--onto <newbase>]
        <upstream> [<branch>]
git rebase [-i | --interactive] [options] --onto <newbase>
        --root [<branch>]
git rebase --continue | --skip | --abort

When i'm executing
git rebase --onto master next topic

master is exactly the new base, new fork point for topic, which was
previously forked from next!

>Said differently, it's
> just _really weird_ that a new argument (for a different mode) shows
> up between two other arguments. It should either be at the beginning,
> or at the end, but in the middle is just awkward, no?
>
> So another solution might be to change the position of the
> <fork_point> in the --onto case.
>
> --
> Cheers,
>
> Sverre Rabbelier
>

Re: git rebase command and docs questions

[Sverre Rabbelier]

Heya,

On Sun, Apr 11, 2010 at 00:30, Eugene Sajine <euguess@gmail.com> wrote:
> How is that possible that it is not an argument to --onto???

What I meant is that it's not "--onto=<value>", "--onto" is a boolean flag.

-- 
Cheers,

Sverre Rabbelier

Re: git rebase command and docs questions

[Eugene Sajine]

On Sat, Apr 10, 2010 at 6:32 PM, Sverre Rabbelier <srabbelier@gmail.com> wrote:
> Heya,
>
> On Sun, Apr 11, 2010 at 00:30, Eugene Sajine <euguess@gmail.com> wrote:
>> How is that possible that it is not an argument to --onto???
>
> What I meant is that it's not "--onto=<value>", "--onto" is a boolean flag.
>
> --
> Cheers,
>
> Sverre Rabbelier
>

Oh, OK. I didn't know that - your paragraph makes sense to me now;)
Thanks!

Still all three questions from original mail are open...

Thanks,
Eugene