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

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

Junio C Hamano wrote:
> Felipe Contreras <felipe.contreras@gmail.com> writes:
> 
> > Revision ranges are one of the most pervasive concepts in Git. It belongs
> > in the glossary.
> >
> > Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
> > ---
> >  Documentation/glossary-content.txt | 4 ++++
> >  1 file changed, 4 insertions(+)
> >
> > diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
> > index 67c7a50b96..31151277ba 100644
> > --- a/Documentation/glossary-content.txt
> > +++ b/Documentation/glossary-content.txt
> > @@ -554,6 +554,10 @@ The most notable example is `HEAD`.
> >  [[def_revision]]revision::
> >  	Synonym for <<def_commit,commit>> (the noun).
> >  
> > +[[def_revision_range]]revision range::
> > +        A syntax to specify a list of commits, usually indicating the starting
> > +        and ending points. For example: `master..@`.
> 
> 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.

> Especially since most people are downstream consumers, I'd
> suggest using `origin..` or `@{u}..` here.

Nobody uses "origin" (what does that even mean?), and @{u} is way too
technical, and something not a lot of people know about (@{upstream}
would be a little less cryptic, but still suffer from the same
disadvantage).

> Either is in line with the spirit of the example in the patch that
> asks "what did I do on my own on this branch since I forked?".

No it wouldn't. I don't have an "origin" head in any of my repositories.

If you really don't want to give a real example (like `master..@`--which
I guarantee does work on 99% of your repositories), then we can go with
'start..end' (it would not work on any real scenario, but neither does
many of your suggestions).

> Incidentally, it also avoids fruitless arguments about what the name
> of the primary integration branch ought to be.

Anybody who wants to get into that first needs to address the issue
that:

  git -C Documentation grep '\bmaster\b' -- \
    SubmittingPatches '*.txt' ':!RelNotes/*'

Returns 799 matching lines (many with more than one instance).

So, if this patch makes it 800, I don't think it would be a significant
factor in transitioning the documentation away from "master" (when and
if that happens).

Today people use "master". When they don't, the glossary can be updated.
It takes a second (which is much less than the time we've spent talking
about it already).

> Also "see the 'Specifying Ranges' and 'Revision Range Summary'
> sections of linkgit:gitrevisions[7] for details" would be a helpful
> addition to readers.

> Since there are examples there, we may even be able to drop "For
> example..." from here and have just refer the readers to these
> sections.

I think we need both. Detailed explanations are good, but so is a
succinct example.

> By the way, this reminds of me one thing that seems to occasionally
> confuse new people.  Most Git commands take a single range, even
> though you can give multiple bottoms and tops.  This is because a
> revision range is *not* just a random "list" of commits, but a single
> connected set of commits, and to new people, the distinction between
> them seems to be a bit unclear.

Yeah, but at this point that's overcomplicating the issue.

For example, if you do master..feature-a, and master..feature-b that
technically can be considered a revision range", since it's something
accepted by `git log`, and `git log` accepts "revision ranges".

But anyone that understands English would say that's not a single
range, but two ranges.

So English and git are at odds in this instance.

I think a..b should be a revision range, and multiple of those could be
called a revision spec (or revspec for short). We have pathspecs, why
not revspecs?

Mercurial for example calls them revsets.

Either way. I'm trying to start from the lowest common denominator.

  1. Revision ranges do exist throughout the documentation
  2. `git log` accepts a revision range

So let's describe what a revision range is, in the simplest form.

The rest can be done later.

Cheers.

-- 
Felipe Contreras