All of
 help / color / mirror / Atom feed
From: Felipe Contreras <>
To: Junio C Hamano <>,
	Felipe Contreras <>
Cc:, "Nguyễn Thái Ngọc Duy" <>,
	"Richard Hansen" <>
Subject: RE: Re* [PATCH] doc: glossary: add entry for revision range
Date: Mon, 17 May 2021 05:30:01 -0500	[thread overview]
Message-ID: <60a245a927c62_126333208ea@natae.notmuch> (raw)
In-Reply-To: <xmqqbl993irp.fsf@gitster.g>

Junio C Hamano wrote:
> Felipe Contreras <> writes:
> > Revision ranges are one of the most pervasive concepts in Git. It belongs
> > in the glossary.
> >
> > Signed-off-by: Felipe Contreras <>
> > ---
> >  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

> 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

  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.


Felipe Contreras

  reply	other threads:[~2021-05-17 10:30 UTC|newest]

Thread overview: 19+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-05-16 20:37 [PATCH] doc: glossary: add entry for revision range Felipe Contreras
2021-05-17  7:46 ` Re* " Junio C Hamano
2021-05-17 10:30   ` Felipe Contreras [this message]
2021-05-17 11:55     ` Jeff King
2021-05-17 17:22       ` Felipe Contreras
2021-05-18  6:59         ` Jeff King
2021-05-18 12:28           ` Felipe Contreras
2021-05-17 19:26       ` Junio C Hamano
2021-05-17 21:05         ` Felipe Contreras
2021-05-18  0:51           ` Junio C Hamano
2021-05-18  1:26             ` Felipe Contreras
2021-05-18  2:08           ` Jeff King
2021-05-18  2:57             ` Junio C Hamano
2021-05-18  5:20               ` Felipe Contreras
2021-05-18  5:02             ` Felipe Contreras
2021-05-18  6:55               ` Jeff King
2021-05-18 11:42                 ` Felipe Contreras
2021-05-18 12:47                   ` Jeff King
2021-05-18 21:09                     ` Felipe Contreras

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=60a245a927c62_126333208ea@natae.notmuch \ \ \ \ \ \

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.