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

jj-vcs · Jan 23, 2025 · d38baae · d38baae
1 parent 98c2881
commit d38baae
Show file tree

Hide file tree

Showing 8 changed files with 99 additions and 47 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -708,7 +708,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-config.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.

diff --git a/cli/src/commands/log.rs b/cli/src/commands/log.rs
@@ -54,9 +54,9 @@ 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.
+/// symbols, see https://jj-vcs.github.io/jj/latest/template-config/#log-nodes.
 #[derive(clap::Args, Clone, Debug)]
 pub(crate) struct LogArgs {
     /// Which revisions to show

diff --git a/cli/tests/[email protected] b/cli/tests/[email protected]
@@ -1361,7 +1361,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/template-config/#log-nodes.
+The working-copy commit is indicated by a `@` symbol in the graph. Immutable revisions (https://jj-vcs.github.io/jj/latest/revset-config/#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]...`
 

diff --git a/docs/config.md b/docs/config.md
@@ -306,43 +306,15 @@ 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.
+You can change which revisions are immutable by setting the
+[`immutable_heads()` revset alias](revset-config.md#immutable_heads).
 
 ## Log
 
 ### Default revisions
 
-You can configure the revisions `jj log` would show when neither `-r` nor any paths are specified.
-
-```toml
-[revsets]
-# Show commits that are not in `main@origin`
-log = "main@origin.."
-```
-
-The default value for `revsets.log` is
-`'present(@) | ancestors(immutable_heads().., 2) | present(trunk())'`.
+You can change which revisions are logged by default with the [`revsets.log`
+setting](revset-config.md#revsets-log).
 
 ### Default Template
 
@@ -381,14 +353,8 @@ To change the presentation of commit and change ids, adjust the
 [`format_short_id()` template alias](template-config.md#format_short_id).  The
 linked doc also explains how to change them separately.
 
-To control which revisions get priority for shorter prefixes, set
-`revsets.short-prefixes`:
-
-```toml
-[revsets]
-# Prioritize the current bookmark
-short-prefixes = "(main..@)::"
-```
+To change which revisions get the shortest prefixes, see [commit and change Id
+short prefixes](revset-config.md#revsets-short-prefixes).
 
 ### Relative timestamps
 

diff --git a/docs/revset-config.md b/docs/revset-config.md
@@ -0,0 +1,85 @@
+# Revset configuration
+
+## Configurable revsets
+
+Settings in the `revsets` section configure Jujutsu itself. These revsets may
+use any [revset aliases](#revset-aliases) that you have defined.
+
+### `log`: Default log revisions {#revsets-log}
+
+You can configure the revisions `jj log` would show when neither `-r` nor any
+paths are specified.
+
+```toml
+[revsets]
+# Show commits that are not in `main@origin`
+log = "main@origin.."
+```
+
+The default value for `revsets.log` is
+`'present(@) | ancestors(immutable_heads().., 2) | present(trunk())'`.
+
+### `short-prefixes`: Commit and change ID short prefixes {#revsets-short-prefixes}
+
+To control which revisions get priority for shorter prefixes, set
+`revsets.short-prefixes`:
+
+```toml
+[revsets]
+# Prioritize the current bookmark
+short-prefixes = "(main..@)::"
+```
+
+## Revset aliases
+
+Some revset aliases are built-in to Jujutsu and used to control its behavior.
+
+See the [revset language reference](revsets.md) for more information about the
+revset language and defining your own revset aliases.
+
+### `trunk()`: Head of the main line of development {#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 the default values for the [log
+revset](#revsets-log) and for
+[`immutable_heads()`](#immutable_heads).
+
+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()`: Change the set of immutable commits {#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())"
+```
diff --git a/docs/revsets.md b/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
@@ -489,7 +489,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-config.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

diff --git a/docs/templates.md b/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-config.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.

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -111,6 +111,7 @@ nav:
 
 - 'Configuration':
       - 'Settings': 'config.md'
+      - 'Revset configuration': 'revset-config.md'
       - 'Template configuration': 'template-config.md'
 
 - 'Comparisons':