Subject: Re: [PATCH v6 17/21] range-diff: populate the man page

From: Ævar Arnfjörð Bjarmason <[email-masked]>
Date: Sun, 09 Sep 2018 19:19:51 +0200

On Sun, Sep 09 2018, SZEDER Gábor wrote:

> On Sun, Sep 09, 2018 at 01:14:25PM +0200, Ævar Arnfjörð Bjarmason wrote:
>>
>> On Mon, Aug 13 2018, Johannes Schindelin via GitGitGadget wrote:
>>
>> I realize this topic has long since landed, just seemed like a good
>> thing to reply to to ask this question:
>>
>> > [...]
>> > +	( <range1> <range2> | <rev1>...<rev2> | <base> <rev1> <rev2> )
>> > [...]
>> > +<range1> <range2>::
>> > +	Compare the commits specified by the two ranges, where
>> > +	`<range1>` is considered an older version of `<range2>`.
>> > +
>> > +<rev1>...<rev2>::
>> > +	Equivalent to passing `<rev2>..<rev1>` and `<rev1>..<rev2>`.
>> > +
>> > +<base> <rev1> <rev2>::
>> > +	Equivalent to passing `<base>..<rev1>` and `<base>..<rev2>`.
>> > +	Note that `<base>` does not need to be the exact branch point
>> > +	of the branches. Example: after rebasing a branch `my-topic`,
>> > +	`git range-diff my-topic@{u} my-topic@{1} my-topic` would
>> > +	show the differences introduced by the rebase.
>>
>> I find myself using range-diff often by watching forced pushes to public
>> repos to see what others are doing, e.g. just now:
>>
>>      + 38b5f0fe72...718fbdedbc split-index-racy       -> szeder/split-index-racy  (forced update)
>
> Heh, spying on my wip bugfixes :)
>
>> And then I turn that into:
>>
>>     # @{u} because I happen to be on 'master' and it's shorter to type
>>     # than origin/master...
>>     git range-diff @{u} 38b5f0fe72...718fbdedbc
>
> I don't understand what you want with that @{u} or 'origin/master' in
> the first place.  It's unnecessary, the three-dot notation on its own
> works just fine.

Maybe I've been using the wrong mode all along, I passed over by habits
from tbdiff, which were surely copy/pasted from somewhere.

Looking at the git-range-diff manpage though it recommends <base> <rev1>
<rev2> over <rev1>...<rev2> when the topic has been rebased, which is
usually the case for e.g. a topic that's submitted to git.git (usually
be the time feedback has been gathered & a re-submission has been made
Junio has pushed another "master").

So isn't "<base> <rev1> <rev2>" the right thing to use over
"<rev1>...<rev2>" for git.git use? I think so, but I'm not sure.

In any case, there are going to be those use-case where you should be
using "<base> <rev1> <rev2>", and a rebase will be propagated by a
force-push, so I thought it made sense that range-diff could directly
consume the output of "fetch" in that case...

>> Only to get an error because it doesn't support that, but just:
>>
>>     git range-diff @{u} 38b5f0fe72 718fbdedbc
>>
>> I think it would be convenient given that "fetch" produces this output
>> to support this sort of invocation as synonymous with the three-arg
>> form. Then you can directly copy/paste that from terminals that have a
>> convenient feature to highlight a continuous \S+ reason to copy/paste
>> it.
>>
>> I can patch it in, but maybe there's UI reasons not to do this that I'm
>> missing, e.g. confusion with the existing <rev1>...<rev2> syntax. What
>> do you think?