On Mon, May 17, 2021 at 05:30:01AM -0500, Felipe Contreras wrote:
> > 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
