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

From: Felipe Contreras <felipe.contreras@gmail.com>
Date: May 17, 2021, 21:05 UTC
Message-ID: <60a2daa57d8a6_13c370208f3@natae.notmuch>
In-Reply-To: <xmqqpmxp6u13.fsf@gitster.g>

Junio C Hamano wrote:

Show 13 quoted lines

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

Show 8 quoted lines

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