Subject: Re: Re* [PATCH] doc: glossary: add entry for revision range

From: Junio C Hamano <[email-masked]>
Date: Tue, 18 May 2021 04:26:48 +0900

Jeff King <[email-masked]> writes:

> I agree that if the purpose is to be illustrative, using shortcuts like
> "an empty endpoint means HEAD" is not helpful. And likewise for "@"; if
> you need to have "revision range" defined, there is a good chance that
> you don't know about shortcuts like "@" either.
>
> So I would prefer something more explicit (whether it's "mybranch" or
> "end" or "HEAD" or whatever).

Perhaps.  Being illustrative for common use case is also important,
so I do not mind teaching "missing endpoint at either side defaults
to HEAD" early.

If "missing" endpoint is disturbing, the description can be fixed to
stress that they are "often but not always" given.

>> > Especially since most people are downstream consumers, I'd
>> > suggest using `origin..` or `@{u}..` here.
>> 
>> Nobody uses "origin" (what does that even mean?), [...]
>
> I guess I'm "nobody" then, because I use it all the time.

Oh, I'm nobody, too, and so are many others ;-)

> The example in Documentation/rev-list-description.txt (which feeds into
> the git-log and git-rev-list manpages) uses "origin..HEAD", as well.
>
> IMHO it is a pretty reasonable example, but the examples in
> gitrevisions(7) use made up "r1..r2", and that seems perfectly readable,
> as well.
>
> -Peff