From 086dced9f6028af9789f74b897fc95234e0dbc69 Mon Sep 17 00:00:00 2001
From: Essien Ita Essien <34972+essiene@users.noreply.github.com>
Date: Thu, 1 Aug 2024 22:12:27 +0100
Subject: [PATCH] Update CHANGELOG and documentation.

---
 CHANGELOG.md    |  4 ++++
 docs/revsets.md | 14 ++++++++++----
 2 files changed, 14 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2ea5ed48eca..56af78d0522 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -44,6 +44,10 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### New features
 
+* Define `immutable_heads()` revset alias in terms of a new `builtin_immutable_heads()`.
+  This enables users to redefine `immutable_heads()` as they wish, but still
+  have `builtin_immutable_heads()` which can not be redefined.
+
 * External diff tools can now be configured to invoke the tool on each file
   individually instead of being passed a directory by setting
   `merge-tools.$TOOL.diff-invocation-mode="file-by-file"` in config.toml.
diff --git a/docs/revsets.md b/docs/revsets.md
index 2b99e9689e1..3d03fb0072c 100644
--- a/docs/revsets.md
+++ b/docs/revsets.md
@@ -404,10 +404,11 @@ For example:
 
 ### Built-in Aliases
 
-The following aliases are built-in and used for certain operations. These functions
+The following aliases are built-in and used for certain operations. Most of these functions
 are defined as aliases in order to allow you to overwrite them as needed. 
 See [revsets.toml](https://github.com/martinvonz/jj/blob/main/cli/src/config/revsets.toml)
-for a comprehensive list.
+for a comprehensive list. There are however [builtins](https://github.com/martinvonz/jj/blob/main/cli/src/config/builtins.toml)
+that can not be overridden nor redefined.
 
 * `trunk()`: Resolves to the head commit for the trunk branch of the remote
   named `origin` or `upstream`. The branches `main`, `master`, and `trunk` are
@@ -426,9 +427,14 @@ for a comprehensive list.
   'trunk()' = 'your-branch@your-remote'
   ```
 
+* `builtin_immutable_heads()`: Resolves to `trunk() | tags() | untracked_remote_branches()`.
+   This builtin **can not** be overridden. It is used as the default definition for
+   `immutable_heads()` below.
+
 * `immutable_heads()`: Resolves to `trunk() | tags() |
-  untracked_remote_branches()` by default. See
-  [here](config.md#set-of-immutable-commits) for details.
+  untracked_remote_branches()` 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.
 
 * `immutable()`: The set of commits that `jj` treats as immutable. This is
   equivalent to `::(immutable_heads() | root())`. Note that modifying this will