Re* [PATCH] doc: glossary: add entry for revision range
- From
Junio C Hamano <gitster@pobox.com>
- Date
- May 17, 2021, 07:46 UTC
- Message-ID
- <xmqqbl993irp.fsf@gitster.g>
- In-Reply-To
- <20210516203736.1098072-1-felipe.contreras@gmail.com>
Felipe Contreras <felipe.contreras@gmail.com> writes:
Show 19 quoted lines
> 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. 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,