docs: Extract well-known revset aliases to their own page

CHANGELOG.md

@@ -685,7 +685,7 @@ Thanks to the people who made this release happen!
 * `jj backout --revision` has been renamed to `jj backout --revisions`.
   The short alias `-r` is still supported.
 
-* [The default `immutable_heads()` set](docs/config.md#set-of-immutable-commits)
+* [The default `immutable_heads()` set](docs/revset-aliases.md#immutable_heads)
   now includes `untracked_remote_branches()` with the assumption that untracked
   branches aren't managed by you. Therefore, untracked branches are no longer
   displayed in `jj log` by default.

cli/src/commands/log.rs

@@ -54,7 +54,7 @@ use crate::ui::Ui;
 /// rendered as a synthetic node labeled "(elided revisions)".
 ///
 /// The working-copy commit is indicated by a `@` symbol in the graph. Immutable
-/// revisions (https://jj-vcs.github.io/jj/latest/config/#set-of-immutable-commits)
+/// revisions (https://jj-vcs.github.io/jj/latest/revset-aliases/#immutable_heads)
 /// have a `◆` symbol. Other commits have a `○` symbol. To customize these
 /// symbols, see https://jj-vcs.github.io/jj/latest/config/#node-style.
 #[derive(clap::Args, Clone, Debug)]

cli/tests/cli-reference@.md.snap

@@ -1356,7 +1356,7 @@ Renders a graphical view of the project's history, ordered with children before
 
 Spans of revisions that are not included in the graph per `--revisions` are rendered as a synthetic node labeled "(elided revisions)".
 
-The working-copy commit is indicated by a `@` symbol in the graph. Immutable revisions (https://jj-vcs.github.io/jj/latest/config/#set-of-immutable-commits) have a `◆` symbol. Other commits have a `○` symbol. To customize these symbols, see https://jj-vcs.github.io/jj/latest/config/#node-style.
+The working-copy commit is indicated by a `@` symbol in the graph. Immutable revisions (https://jj-vcs.github.io/jj/latest/revset-aliases/#immutable_heads) have a `◆` symbol. Other commits have a `○` symbol. To customize these symbols, see https://jj-vcs.github.io/jj/latest/config/#node-style.
 
 **Usage:** `jj log [OPTIONS] [FILESETS]...`
 

docs/config.md

@@ -318,31 +318,6 @@ conflict-marker-style = "git"
 For more details about these conflict marker styles, see the [conflicts
 page](conflicts.md#conflict-markers).
 
-### Set of immutable commits
-
-You can configure the set of immutable commits via
-`revset-aliases."immutable_heads()"`. The default set of immutable heads is
-`builtin_immutable_heads()`, which in turn is defined as
-`present(trunk()) | tags() | untracked_remote_bookmarks()`. For example, to
-also consider the `release@origin` bookmark immutable:
-
-```toml
-[revset-aliases]
-"immutable_heads()" = "builtin_immutable_heads() | release@origin"
-```
-
-To prevent rewriting commits authored by other users:
-
-```toml
-# The `trunk().. &` bit is an optimization to scan for non-`mine()` commits
-# only among commits that are not in `trunk()`.
-[revset-aliases]
-"immutable_heads()" = "builtin_immutable_heads() | (trunk().. & ~mine())"
-```
-
-Ancestors of the configured set are also immutable. The root commit is always
-immutable even if the set is empty.
-
 ## Log
 
 ### Default revisions

docs/revset-aliases.md

@@ -0,0 +1,51 @@
+# Revset aliases
+
+Some revset aliases are built-in to Jujutsu and used to control its behavior.
+
+See [Revset language](revsets.md) for information about the revset syntax.
+
+## `trunk()`
+
+Most teams have a main line of development, usually named `main`, `master`, or
+`trunk`. The `trunk()` alias resolves to the bookmark for this branch.
+
+This alias is used in other built-in aliases, it is not used directly by
+Jujutsu.
+
+When Jujutsu clones a Git repository, it uses the remote's HEAD to set this
+revset aliases in the repo's config.
+
+```toml
+[revset-aliases]
+"trunk()" = "dev@origin"
+```
+
+## `immutable_heads()`
+
+Controls which commits are immutable. Jujutsu will refuse to modify these
+commits unless `--ignore-immutable` is specified.
+
+Many teams have a main line of development, usually named `main`, `master`, or
+`trunk`.
+
+Ancestors of the configured set are also immutable. The root commit is always
+immutable even if the set is empty.
+
+Default value: `builtin_immutable_heads()`, which in turn is defined as
+`present(trunk()) | tags() | untracked_remote_bookmarks()`.
+
+For example, to also consider the `release@origin` bookmark immutable:
+
+```toml
+[revset-aliases]
+"immutable_heads()" = "builtin_immutable_heads() | release@origin"
+```
+
+To prevent rewriting commits authored by other users:
+
+```toml
+# The `trunk().. &` bit is an optimization to scan for non-`mine()` commits
+# only among commits that are not in `trunk()`.
+[revset-aliases]
+"immutable_heads()" = "builtin_immutable_heads() | (trunk().. & ~mine())"
+```

docs/revsets.md

@@ -1,4 +1,4 @@
-# Revsets
+# Revset language
 
 Jujutsu supports a functional language for selecting a set of revisions.
 Expressions in this language are called "revsets" (the idea comes from
@@ -467,7 +467,7 @@ for a comprehensive list.
 * `immutable_heads()`: Resolves to
   `present(trunk()) | tags() | untracked_remote_bookmarks()` by default. It is
   actually defined as `builtin_immutable_heads()`, and can be overridden as
-  required. See [here](config.md#set-of-immutable-commits) for details.
+  required. See [here](revset-aliases.md#immutable_heads) for details.
 
 * `immutable()`: The set of commits that `jj` treats as immutable. This is
   equivalent to `::(immutable_heads() | root())`. It is not recommended to redefine

docs/templates.md

@@ -113,7 +113,7 @@ This type cannot be printed. The following methods are defined.
   visible commits.
 * `hidden() -> Boolean`: True if the commit is not visible (a.k.a. abandoned).
 * `immutable() -> Boolean`: True if the commit is included in [the set of
-  immutable commits](config.md#set-of-immutable-commits).
+  immutable commits](revset-aliases.md#immutable_heads).
 * `contained_in(revset: String) -> Boolean`: True if the commit is included in [the provided revset](revsets.md).
 * `conflict() -> Boolean`: True if the commit contains merge conflicts.
 * `empty() -> Boolean`: True if the commit modifies no files.

mkdocs.yml

@@ -111,6 +111,7 @@ nav:
 
 - 'Configuration':
       - 'Settings': 'config.md'
+      - 'Revset aliases': 'revset-aliases.md'
       - 'Template aliases': 'template-aliases.md'
 
 - 'Comparisons':