Re: RFC: Renaming "git rebase --onto"

[Michael J Gruber <git@drmicha.warpmail.net>]

Junio C Hamano venit, vidit, dixit 30.03.2015 23:12:
> Jonathon Mah <me@JonathonMah.com> writes:
> 
>> During a few years of discussing git operations with colleagues, I’ve
>> found the “git rebase --onto” operation particularly ambiguous. The
>> reason is that I always describe a rebase operation as “onto”
>> something else (because of the English phrase “A is based on
>> B”). For example:
>>
>> $ git rebase new-base  # “Rebase HEAD onto new-base (from merge-base of HEAD and new-base)"
>> $ git rebase new-base my-branch # “Rebase my-branch onto new-base
>> (from merge-base of my-branch and new-base)”
>>
>> Personally, I understand “git-rebase --onto new-base old-base” as
>> meaning “rebase from old-base to new-base”. Some prepositions that
>> might make this clearer:
>>
>> $ git rebase --from old-base new-base  # “Rebase HEAD onto new-base, from old-base"
>> $ git rebase --after old-base new-base # “Rebase commits on HEAD
>> after old-base HEAD onto new-base"
>> $ git rebase --excluding old-base new-base # “Rebase HEAD onto
>> new-base, excluding commit old-base (and its parents)"
>>
>> In all cases this would change the order of the arguments compared to
>> --onto, making it more consistent with the no-option rebase.
> 
> The bog-standard rebase is
> 
>     git rebase U
> 
> which rebases the current history that has diverged from the history
> leading to U on to U.
> 
> Or
> 
>     git rebase U BRANCH
> 
> which rebases BRANCH that has diverged from the history leading to U
> on to U.  In both of these invocations, these arguments define which
> part of the local history is replayed.
> 
> Now,
> 
>     git rebase [--onto O] $other_args
> 
> is just a way to say $other_args still define which part of the
> local history is replayed, but you are replaying on something that
> is different from the usual default case (which is U).
> 
> Which feels very consistent between the cases with and without the
> extra --onto parameter, at least to me.  Hence, if you change order
> in any way, I would think you would break the existing consistency.
> 
> I suspect that this thread is a symptom of something unrelated,
> though.  There might be something wrong in your workflow if you find
> yourself using --onto too often, for example, and that may be the
> issue we should be focusing on, not on how "rebase --onto" is
> spelled.
> 
>> What do others think? Is my view of “onto” common or unusual?
> 
> "common or unusual" is a question we cannot answer, I would say.
> People who are used to "rebase" may be so used to it that it might
> feel natural to them but cannot tell if that is only because they
> already know how "rebase" spells its arguments, or they would still
> find it natural if they did not know anything about "rebase".
> 

The basic confusion comes from the natural desire to read a command as a
sentence, and the lack of the rebase UI in that respect:

"git rebase foo" does not "rebase foo"!

"git rebase foo bar" does not "rebase foo" either!

I think it's a UI design mistake that comes from making the common
use-case as short as possible.

In the invocations above, "foo" is neither the ref that is being rebased
nor a rev notation for the affected commits. That would have been foo..
or ^foo.

I seem to recall that we've talked about range notations for rebase.
Maybe we can start accepting them, and once we start teaching "git
rebase ^foo" or "git rebase foo.." it will become clearer that that
argument is not the ref being rebased, but a description of the commits
being rebased. And then it would be natural to talk about "onto foo" for
these cases, as well as leave the "--onto" argument named the way it is
(since it defaults to foo, or rather the fork-point).

Michael