[PATCH] doc: revisions: improve single range explanation
The original explanation didn't seem clear enough to some people.
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
Documentation/revisions.txt | 22 +++++++++++-----------
1 file changed, 11 insertions(+), 11 deletions(-)
diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index f5f17b65a1..d8cf512686 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -299,22 +299,22 @@ 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
+they are exceptions. Unless otherwise noted, all git commands
that operate on a set of commits work on a single revision range.
-In other words, writing two "two-dot range notation" next to each
-other, e.g.
- $ git log A..B C..D
+For example, if you have a linear history like this:
-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 B or D but are reachable from neither A or C.
-In a linear history like this:
+ ---A---B---C---D---E---F
- ---A---B---o---o---C---D
+Doing A..F will retrieve 5 commits, and doing B..E will retrieve 3
+commits, but doing A..F B..E will not retrieve two revision ranges
+totalling 8 commits. Instead the starting point A gets overriden by B,
+and the ending point of E by F, effectively becoming B..F, a single
+revision range.
-because A and B are reachable from C, the revision range specified
-by these two dotted ranges is a single commit D.
+With more complex graphs the result is not so simple and might result in
+two disconnected sets of commits, but that is still considered a single
+revision range.
Other <rev>{caret} Parent Shorthand Notations
--
2.32.0
Felipe Contreras <felipe.contreras@gmail.com>