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

[Felipe Contreras <felipe.contreras@gmail.com>]

Junio C Hamano wrote:
> Jeff King <peff@peff.net> writes:
> 
> > 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.

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