diff --git a/docs/config.md b/docs/config.md
index 7b9597b4991..829cc84289d 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -328,24 +328,16 @@ Can be customized by the `format_short_signature()` template alias.
 
 ### Allow "large" revsets by default
 
-Certain commands (such as `jj rebase`) can take multiple revset arguments, and
-each of these may resolve to one-or-many revisions. By default, `jj` will not
-allow revsets that resolve to more than one revision — a so-called "large
-revset" — and will ask you to confirm that you want to proceed by
-prefixing it with the `all:` modifier.
+By default, `jj` requires the `all:` prefix for many commands to accept a revset
+that expands to multiple arguments (AKA "large revsets") as a safety check. See
+[the docs for `all:`](revsets.md#the-all-prefix) for details. 
 
-For instance, to add a new parent `abc` to the commit `xyz`, you may use `jj
-rebase`:
-
-```
-jj rebase -r xyz -d "all:xyz-" -d "abc"
-```
-
-`jj` requires the `all:` prefix for the above command. However, you may disable
-this behavior by setting `ui.always-allow-large-revsets` to `true`:
+However, you may disable this check by setting `ui.always-allow-large-revsets`
+to `true`. Then, `jj` will no longer require the `all:` prefix to revsets for
+any commands that otherwise would.
 
 ```toml
-ui.always-allow-large-revsets = true
+ui.always-allow-large-revsets = true  # Assume `all:` prefix whenever it would make a difference
 ```
 
 ## Pager
diff --git a/docs/revsets.md b/docs/revsets.md
index 5370a6b0e8e..eec587ac537 100644
--- a/docs/revsets.md
+++ b/docs/revsets.md
@@ -70,6 +70,7 @@ only symbols.
 You can use parentheses to control evaluation order, such as `(x & y) | z` or
 `x & (y | z)`.
 
+
 ## Functions
 
 You can also specify revisions by using functions. Some functions take other
@@ -218,6 +219,40 @@ for a comprehensive list.
 * `immutable_heads()`: Resolves to `trunk() | tags()` by default. See
   [here](config.md#set-of-immutable-commits) for details.
 
+
+## The `all:` modifier
+
+Certain commands (such as `jj rebase`) can take multiple revset arguments, and
+each of these may resolve to one-or-many revisions. By default, `jj` will not
+allow revsets that resolve to more than one revision — a so-called "large
+revset" — and will ask you to confirm that you want to proceed by
+prefixing it with the `all:` modifier.
+
+If you set the `ui.always-allow-large-revsets` option to `true`, `jj` will
+behave as though the `all:` modifier was used every time it would matter.
+
+An `all:` modifier before a revset expression does not otherwise change its
+meaning. Strictly speaking, it is not part of the revset language. The notation
+is similar to the modifiers like `glob:` allowed before [string
+patterms](#string-patterns).
+
+For example, `jj rebase -r w -d xyz+` will rebase `w` on top of the child of
+`xyz` as long as `xyz` has exactly one child.
+
+If `xyz` has more than one child, the `all:` modifier is *not* specified, and
+`ui.always-allow-large-revsets` is `false` (the default), `jj rebase -r w -d
+xyz+` will return an error.
+
+If `ui.always-allow-large-revsets` was `true`, the above command would act as if
+`all:` was set (see the next paragraph).
+
+With the `all:` modifier, `jj rebase -r w -d all:xyz+` will make `w` into a merge
+commit if `xyz` has more than one child. The `all:` modifier confirms that the
+user expected `xyz` to have more than one child.
+
+A more useful example: if `w` is a merge commit, `jj rebase -s w -d all:w- -d
+xyz` will add `xyz` to the list of `w`'s parents.
+
 ## Examples
 
 Show the parent(s) of the working-copy commit (like `git log -1 HEAD`):