From 34c93c4de0b3ae6774efe77e93ab46c334b6e062 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 modifier for revsets 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 | 23 +++++++++-------------- docs/revsets.md | 34 ++++++++++++++++++++++++++++++++++ 2 files changed, 43 insertions(+), 14 deletions(-) diff --git a/docs/config.md b/docs/config.md index 7b9597b499..bc41dd81dc 100644 --- a/docs/config.md +++ b/docs/config.md @@ -328,23 +328,18 @@ 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. +Certain commands (such as `jj rebase`) can take multiple revset arguments, but +default to requiring each of those revsets to expand to a *single* revision. +This restriction can be overridden by prefixing a revset that the user wants to +be able to expand to more than one revision with the [`all:` +modifier](revsets.md#the-all-modifier). -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`: +Another way you can override this check is by setting +`ui.always-allow-large-revsets` to `true`. Then, `jj` will allow every one of +the revset arguments of such commands to expand to any number of revisions. ```toml +# Assume `all:` prefix before revsets whenever it would make a difference ui.always-allow-large-revsets = true ``` diff --git a/docs/revsets.md b/docs/revsets.md index 5370a6b0e8..af956529cd 100644 --- a/docs/revsets.md +++ b/docs/revsets.md @@ -218,6 +218,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`):