Felipe Contreras <felipe.contreras@xxxxxxxxx> writes:
> Revision ranges are one of the most pervasive concepts in Git. It belongs
> in the glossary.
>
> Signed-off-by: Felipe Contreras <felipe.contreras@xxxxxxxxx>
> ---
> 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
+r3.
+
+
Other <rev>{caret} Parent Shorthand Notations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Three other shorthands exist, particularly useful for merge commits,
