From 9210a11ea04ef703be55e8ee491c819fff316d32 Mon Sep 17 00:00:00 2001 From: Ilya Grigoriev Date: Thu, 11 Apr 2024 12:01:26 -0700 Subject: [PATCH] revsets.md: document the `all:` prefix While this is arguably not part of the revset language, this is a likely place for a user to look. See https://discord.com/channels/968932220549103686/968932220549103689/1228065431281995837 --- docs/config.md | 22 +++++++--------------- docs/revsets.md | 32 ++++++++++++++++++++++++++++++++ 2 files changed, 39 insertions(+), 15 deletions(-) diff --git a/docs/config.md b/docs/config.md index 7b9597b499..829cc84289 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 5370a6b0e8..db50263f51 100644 --- a/docs/revsets.md +++ b/docs/revsets.md @@ -70,6 +70,38 @@ only symbols. You can use parentheses to control evaluation order, such as `(x & y) | z` or `x & (y | z)`. +### The `all:` prefix + +An `all:` prefix before a revset expression does not change its meansing. +Strictly speaking, it is not part of the revset language. The notation is +similar to the prefixes allowed before [string patterms](#string-patterns). + +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. + +Alternatively, you can set the `ui.always-allow-large-revsets` option to `true`. + +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:` prefix 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:` prefix, `jj rebase -r w -d all:xyz+` will make `w` into a merge +commit if `xyz` has more than one child. The `all:` prefix 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. + + ## Functions You can also specify revisions by using functions. Some functions take other