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

Junio C Hamano wrote:

Jeff King [off-list ref] writes:

quoted

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.

A glossary is not a place to teach (anything other than the definition).
It's supposed to contain glosses (brief explanations).

You don't find a complete recipe when you look for the definition of
"recpipe". That information belongs elsewhere.

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

This is unnecessary information.

If we teach that then we also have to teach that the starting point is
not always given either (`..mybranch`). And where does it end? We would
have to teach that `mybranch ^master` is yet another form of a revision
range, and so is -1.

That's what gitrevisions(7) is for.

quoted

quoted

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.

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

That depends on the definition of "many". My guess is that it's less
than 1% of users (probably 0.01%), and for me that's not many.

If you google for `git remote "set-head"` there's barely any
information. It's basically all online man pages.

I don't think anyone can argue it's not obscure.

Cheers.

-- 
Felipe Contreras