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

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

quoted

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.

quoted

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