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

From: Junio C Hamano <gitster@pobox.com>
Date: May 17, 2021, 19:26 UTC
Message-ID: <xmqqpmxp6u13.fsf@gitster.g>
In-Reply-To: <YKJZt4vFECoLZhc2@coredump.intra.peff.net>

Jeff King <peff@peff.net> writes:

Show 7 quoted lines

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

Show 6 quoted lines

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

Show 8 quoted lines

> 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