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

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:

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 :)

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.

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?