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

From: Jeff King <peff@peff.net>
Date: May 17, 2021, 11:55 UTC
Message-ID: <YKJZt4vFECoLZhc2@coredump.intra.peff.net>
In-Reply-To: <60a245a927c62_126333208ea@natae.notmuch>

On Mon, May 17, 2021 at 05:30:01AM -0500, Felipe Contreras wrote:

Show 10 quoted lines

> > As there is no need to spell out HEAD, `master..` would be a better
> > example.
> 
> I don't think so. The description said _starting_ and _ending_ points...
> `master..` has no ending point.
> 
> If we must not use @, then I would rather use `master..mybranch`, or
> something like that. HEAD seems like a technical accident. But of course
> I would prefer HEAD to nothing, because at least it qualifies as an
> ending point.

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

In a more fleshed-out description it might be nice to casually introduce such shortcuts to let the user pick them up naturally, but in a one-liner like a glossary entry, I think clarity is the most important thing.

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

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