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

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

On Sun, Sep 09, 2018 at 01:14:25PM +0200, Ævar Arnfjörð Bjarmason wrote:

quoted

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:

quoted

[...]
+	( <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 :)

quoted

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

quoted

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?