mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: Junio C Hamano <>
To: Felipe Contreras <>
Cc:, "Nguyễn Thái Ngọc Duy" <>,
	"Richard Hansen" <>
Subject: Re* [PATCH] doc: glossary: add entry for revision range
Date: Mon, 17 May 2021 16:46:02 +0900	[thread overview]
Message-ID: <xmqqbl993irp.fsf@gitster.g> (raw)

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.  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
 Other <rev>{caret} Parent Shorthand Notations
 Three other shorthands exist, particularly useful for merge commits,

  reply	other threads:[~2021-05-17  7:46 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 ` Junio C Hamano [this message]
2021-05-17 10:30   ` Re* " Felipe Contreras
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:

  List information:

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

  git send-email \
    --in-reply-to=xmqqbl993irp.fsf@gitster.g \ \ \ \ \ \

* 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.
Code repositories for project(s) associated with this public inbox

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).