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

Revision ranges are one of the most pervasive concepts in Git. It belongs
in the glossary.

Signed-off-by: Felipe Contreras <redacted>
---
 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..@`.
+
 [[def_rewind]]rewind::
 	To throw away part of the development, i.e. to assign the
 	<<def_head,head>> to an earlier <<def_revision,revision>>.

-- 
2.31.1

Felipe Contreras [off-list ref] writes:

As there is no need to spell out HEAD, `master..` would be a better
example.  Especially since most people are downstream consumers, I'd
suggest using `origin..` or `@{u}..` here.  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?".  Incidentally, it also
avoids fruitless arguments about what the name of the primary
integration branch ought to be.

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.

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.

We may want to clarify with something like the following.

 Documentation/revisions.txt | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git c/Documentation/revisions.txt w/Documentation/revisions.txt
index d9169c062e..2b7d8e3745 100644
--- c/Documentation/revisions.txt
+++ w/Documentation/revisions.txt

@@ -260,6 +260,9 @@ any of the given commits.
 A commit's reachable set is the commit itself and the commits in
 its ancestry chain.
 
+There are several notations to specify a set of connected commits
+(called a "revision range"), illustrated below.
+
 
 Commit Exclusions
 ~~~~~~~~~~~~~~~~~

@@ -294,6 +297,20 @@ is a shorthand for 'HEAD..origin' and asks "What did the origin do since
 I forked from them?"  Note that '..' would mean 'HEAD..HEAD' which is an
 empty range that is both reachable and unreachable from HEAD.
 
+Commands that are specifically designed to take two distinct ranges
+(e.g. "git range-diff R1 R2" to compare two ranges) do exist, but
+they are exceptions.  Unless otherwise noted, all "git" commands
+that operate on set of commits work on a single revision range.  In
+other words, giving two dotted ranges next to each other, e.g.
+
+    $ git log 'r1..r2' 'r3..r4'
+
+does *not* specify two revision ranges for most commands.  Instead
+it will name a single connected set of commits, i.e. those that are
+reachable from either r2 or r4 but are reachable from neither r1 or
+r3.
+
+
 Other <rev>{caret} Parent Shorthand Notations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Three other shorthands exist, particularly useful for merge commits,

Junio C Hamano wrote:

Felipe Contreras [off-list ref] writes:

quoted

Revision ranges are one of the most pervasive concepts in Git. It belongs
in the glossary.

Signed-off-by: Felipe Contreras <redacted>
---
 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

On Mon, May 17, 2021 at 05:30:01AM -0500, Felipe Contreras wrote:

quoted

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.

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

In a more fleshed-out description it might be nice to casually introduce
such shortcuts to let the user pick them up naturally, but in a
one-liner like a glossary entry, I think clarity is the most important
thing.

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.

The example in Documentation/rev-list-description.txt (which feeds into
the git-log and git-rev-list manpages) uses "origin..HEAD", as well.

IMHO it is a pretty reasonable example, but the examples in
gitrevisions(7) use made up "r1..r2", and that seems perfectly readable,
as well.

-Peff

Jeff King wrote:

On Mon, May 17, 2021 at 05:30:01AM -0500, Felipe Contreras wrote:

quoted

quoted

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.

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.

But they don't need to know what @ means; it's clearly a shortcut for
_something_, and that's all they need to know. In fact, I'd say most
people can quickly realize what a shorcut for it is, which is why it was
picked by the git project, and many Mercurial projects as well.

Sure the same argument applies to HEAD too, but if we are going to pick
a placeholder for _something_ the user doesn't need to know about, then
@ is much simpler than HEAD.

We could do X too (typically used for _whatever_), but I'd argue @ is
much better than X because it actually works, and not just works, but
it's what the user most often would use.

So I would prefer something more explicit (whether it's "mybranch" or
"end" or "HEAD" or whatever).

I prefer something less explicit, because it's not relevant what X is,
just that it is an end point.

But if you feel strongly about it, "mybranch" it is.

Actually, I would prefer something more real, like "feature-x".

In a more fleshed-out description it might be nice to casually introduce
such shortcuts to let the user pick them up naturally, but in a
one-liner like a glossary entry, I think clarity is the most important
thing.

Indeed, but I find `master..@` is a perfectly clear example of a
revision range from something to something.

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.

Language is rarely 100% specific. By "nobody" of course I meant
"virtually nobody".

And yeah, I know you actually use "origin", because you do have correct
"origin/HEAD" for many of your repositories. I don't, and I'd argume
most users don't either.

It's right next in my to-do list to work on fetch.updateHead so I (and
many users) can join you in using "origin". But that's not the case
today.

The example in Documentation/rev-list-description.txt (which feeds into
the git-log and git-rev-list manpages) uses "origin..HEAD", as well.

I think it shouldn't, but that's a separate topic.

IMHO it is a pretty reasonable example, but the examples in
gitrevisions(7) use made up "r1..r2", and that seems perfectly readable,
as well.

It is readable, sure, but it's not a real example. When picking an
example of English sentence with subject and predicate I'd pick "Mary
went to the moves" over "Subject predicate" in heartbeat.

An instance that doesn't come from the set of real commands is not
really an example to me.

Cheers.

-- 
Felipe Contreras

On Mon, May 17, 2021 at 12:22:56PM -0500, Felipe Contreras wrote:

quoted

quoted

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.

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.

But they don't need to know what @ means; it's clearly a shortcut for
_something_, and that's all they need to know. In fact, I'd say most
people can quickly realize what a shorcut for it is, which is why it was
picked by the git project, and many Mercurial projects as well.

That's my point. It _isn't_ clearly a shortcut for something for all
people. If you are reading the glossary entry for "revision range", you
might not know about the ".." syntax at all. So what does:

  foo..@

mean? Does it parse as three (foo, .., @) or is "..@" a special symbol?

I expect most people would figure it out. But if your point is to serve
as documentation, especially for people who do not yet know all of the
concepts, then why not try to reduce the chance of error as much as
possible?

Actually, I would prefer something more real, like "feature-x".

Sure, that is fine with me.

-Peff

Jeff King wrote:

On Mon, May 17, 2021 at 12:22:56PM -0500, Felipe Contreras wrote:

quoted

quoted

quoted

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.

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.

But they don't need to know what @ means; it's clearly a shortcut for
_something_, and that's all they need to know. In fact, I'd say most
people can quickly realize what a shorcut for it is, which is why it was
picked by the git project, and many Mercurial projects as well.

That's my point. It _isn't_ clearly a shortcut for something for all
people. If you are reading the glossary entry for "revision range", you
might not know about the ".." syntax at all. So what does:

  foo..@

mean?

An ellipsis is a common feature of both human and computer languages...

  The ... fox jumps ...

Is easily understood by most English speakers, so is a, b, c ... z.

It is used in math as well 1, 2, 3,..., 100.

It's used in computer languages, like Pascal, Modula, Oberon, Ada,
Haskell, Perl, Ruby, Swift, Kotlin, F#, and MATLAB.

  (1..10).each { |i| puts i }

I think most readers would infer that a) the starting point is at the
left of the ending point b) there's nothing after the ending point.

So what could the thing at the right of the starting point, follwing an
ellipsis, and not followed by anything else be? I think most people
would get it.

I expect most people would figure it out. But if your point is to serve
as documentation, especially for people who do not yet know all of the
concepts, then why not try to reduce the chance of error as much as
possible?

We want to minimize the chances of error... up to a point. We also want
to be useful.

Moreover, most readers don't learn at the speed they read, it takes
time, and often practice. Copy-pasting `master..@` to their terminal
will most likely work, and with any luck they'll understand it right
away.

They don't need to understand revision ranges completely when they read
the glossary, they just need a brief explanation.

[1] https://en.wikipedia.org/wiki/Ellipsis

-- 
Felipe Contreras