From 4d08c2cce81b6b9befa6960e02545e2888f6005a Mon Sep 17 00:00:00 2001
From: Martin von Zweigbergk <martinvonz@google.com>
Date: Sun, 16 Jun 2024 15:34:54 -0700
Subject: [PATCH] docs: include examples for operators

There's been a lot of questions about the subtle differences between
`..` and `::`. I hope these examples will help with that.

We should also add examples to the revset functions (e.g. `heads()` is
not obvious how it works), but that can come later.
---
 docs/revsets.md | 138 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 138 insertions(+)

diff --git a/docs/revsets.md b/docs/revsets.md
index bb5b8a6d6..be7b165e7 100644
--- a/docs/revsets.md
+++ b/docs/revsets.md
@@ -78,6 +78,144 @@ only symbols.
 You can use parentheses to control evaluation order, such as `(x & y) | z` or
 `x & (y | z)`.
 
+<details>
+<summary>Examples:</summary>
+
+Given this history:
+```
+D
+|\
+| o C
+| |
+o | B
+|/
+o A
+|
+o root()
+```
+
+**Operator** `x-`
+
+`D-` ⇒ `{C,B}`
+
+`B-` ⇒ `{A}`
+
+`A-` ⇒ `{root()}`
+
+`root()-` ⇒ `{}` (empty set)
+
+`none()-` ⇒ `{}` (empty set)
+
+`(D|A)-` ⇒ `{C,B,root()}`
+
+`(C|B)-` ⇒ `{A}`
+
+**Operator** `x+`
+
+`D+` ⇒ `{}` (empty set)
+
+`B+` ⇒ `{D}`
+
+`A+` ⇒ `{B,C}`
+
+`root()+` ⇒ `{A}`
+
+`none()+` ⇒ `{}` (empty set)
+
+`(C|B)+` ⇒ `{D}`
+
+`(B|root())+` ⇒ `{D,A}`
+
+**Operator** `x::`
+
+`D::` ⇒ `{D}`
+
+`B::` ⇒ `{D,B}`
+
+`A::` ⇒ `{D,C,B,A}`
+
+`root()::` ⇒ `{D,C,B,A,root()}`
+
+`::none()` ⇒ `{}` (empty set)
+
+`(C|B)::` ⇒ `{D,C,B}`
+
+**Operator** `x..`
+
+`D..` ⇒ `{}` (empty set)
+
+`B..` ⇒ `{D,C}` (note that, unlike `B::`, this includes `C`)
+
+`A..` ⇒ `{D,C,B}`
+
+`root()..` ⇒ `{D,C,B,A}`
+
+`none()..` ⇒ `{D,C,B,A,root()}`
+
+`(C|B)..` ⇒ `{D}`
+
+**Operator** `::x`
+
+`::D` ⇒ `{D,C,B,A,root()}`
+
+`::B` ⇒ `{B,A,root()}`
+
+`::A` ⇒ `{A,root()}`
+
+`::root()` ⇒ `{root()}`
+
+`::none()` ⇒ `{}` (empty set)
+
+`::(C|B)` ⇒ `{C,B,A,root()}`
+
+**Operator** `..x`
+
+`..D` ⇒ `{D,C,B,A}`
+
+`..B` ⇒ `{B,A}`
+
+`..A` ⇒ `{A}`
+
+`..root()` ⇒ `{}` (empty set)
+
+`..none()` ⇒ `{}` (empty set)
+
+`..(C|B)` ⇒ `{C,B,A}`
+
+**Operator** `x::y`
+
+`D::D` ⇒ `{D}`
+
+`B::D` ⇒ `{D,B}` (note that, unlike `B..D`, this includes `B` and excludes `C`)
+
+`A::D` ⇒ `{D,C,B,A}`
+
+`root()::D` ⇒ `{D,C,B,A,root()}`
+
+`none()::D` ⇒ `{}` (empty set)
+
+`D::B` ⇒ `{}` (empty set)
+
+`(C|B)::(C|B)` ⇒ `{C,B}`
+
+**Operator** `x..y`
+
+`D..D` ⇒ `{}` (empty set)
+
+`B..D` ⇒ `{D,C}` (note that, unlike `B::D`, this includes `C` and excludes `B`)
+
+`A..D` ⇒ `{D,C,B}`
+
+`root()..D` ⇒ `{D,C,B,A}`
+
+`none()..D` ⇒ `{D,C,B,A,root()}`
+
+`D..B` ⇒ `{}` (empty set)
+
+`(C|B)..(C|B)` ⇒ `{}` (empty set)
+
+</details>
+
 ## Functions
 
 You can also specify revisions by using functions. Some functions take other