docs: update examples of divergence to include change offsets

cli/src/commands/log.rs

@@ -61,7 +61,7 @@ use crate::ui::Ui;
 /// [Immutable revisions] have a `◆` symbol. Other commits have a `○` symbol.
 /// All of these symbols can be [customized].
 ///
-/// Changes with a ?? after their ID are [divergent].
+/// Visible changes with a [change offset] after their ID are [divergent].
 ///
 /// [Immutable revisions]:
 ///     https://docs.jj-vcs.dev/latest/config/#set-of-immutable-commits
@@ -69,6 +69,9 @@ use crate::ui::Ui;
 /// [customized]:
 ///     https://docs.jj-vcs.dev/latest/config/#node-style
 ///
+/// [change offset]:
+///     https://docs.jj-vcs.dev/latest/glossary/#change-offset
+///
 /// [divergent]:
 ///     https://docs.jj-vcs.dev/latest/guides/divergence/
 #[derive(clap::Args, Clone, Debug)]

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

@@ -2,7 +2,6 @@
 source: cli/tests/test_generate_md_cli_help.rs
 description: "AUTO-GENERATED FILE, DO NOT EDIT. This cli reference is generated by a test as an `insta` snapshot. MkDocs includes this snapshot from docs/cli-reference.md."
 ---
-
 <!-- BEGIN MARKDOWN-->
 
 # Command-Line Help for `jj`
@@ -1809,12 +1808,14 @@ Spans of revisions that are not included in the graph per `--revisions` are rend
 
 The working-copy commit is indicated by a `@` symbol in the graph. [Immutable revisions] have a `◆` symbol. Other commits have a `○` symbol. All of these symbols can be [customized].
 
-Changes with a ?? after their ID are [divergent].
+Visible changes with a [change offset] after their ID are [divergent].
 
 [Immutable revisions]: https://docs.jj-vcs.dev/latest/config/#set-of-immutable-commits
 
 [customized]: https://docs.jj-vcs.dev/latest/config/#node-style
 
+[change offset]: https://docs.jj-vcs.dev/latest/glossary/#change-offset
+
 [divergent]: https://docs.jj-vcs.dev/latest/guides/divergence/
 
 **Usage:** `jj log [OPTIONS] [FILESETS]...`

docs/FAQ.md

@@ -352,18 +352,20 @@ $ jj evolog
 @  lnvvtrzo jjfan@example.org 2025-02-28 21:01:10 31a347e0
 │  featureA
 │  -- operation 3cb7392c092c snapshot working copy
-○  lnvvtrzo hidden jjfan@example.org 2025-02-28 21:00:51 b8004ab8
+○  lnvvtrzo/1 hidden jjfan@example.org 2025-02-28 21:00:51 b8004ab8
 │  featureA
 │  -- operation 1280bfaec893 snapshot working copy
-○  lnvvtrzo hidden jjfan@example.org 2025-02-28 20:50:05 e4d831d
+○  lnvvtrzo/2 hidden jjfan@example.org 2025-02-28 20:50:05 e4d831d
    (no description set)
    -- operation 0418a5aa94b5 snapshot working copy
 ```
 
 Since commit `b800` is hidden, it is considered obsolete and `jj log` (without
-arguments) will not show it, nor can it be accessed by its change ID `lnvvtrzo`.
-However, most `jj` operations work normally on such commits if you refer to them
-by their commit ID.
+arguments) will not show it. However, most `jj` operations work normally on
+such commits if you refer to them by their commit ID. Hidden commits can also
+be referred to by their change ID, but they require a
+[change offset][glossary_change_offset] to distinguish them (e.g. `b800` can
+also be referred to as `lnv/1`, as shown in the evolog).
 
 To find out which of these versions is the last time before we started working
 on feature B (the point where we should have created a new change, but failed to
@@ -383,7 +385,7 @@ $ jj evolog --patch --git  # We use `--git` to make diffs clear without colors
 │  @@ -1,1 +1,2 @@
 │   Done with feature A
 │  +Working on feature B
-○  lnvvtrzo hidden jjfan@example.org 2025-02-28 21:00:51 b8004ab8
+○  lnvvtrzo/1 hidden jjfan@example.org 2025-02-28 21:00:51 b8004ab8
 │  featureA
 │  -- operation 1280bfaec893 snapshot working copy
 │  diff --git a/file b/file
@@ -393,7 +395,7 @@ $ jj evolog --patch --git  # We use `--git` to make diffs clear without colors
 │  @@ -1,1 +1,1 @@
 │  -Working on feature A
 │  +Done with feature A
-○  lnvvtrzo hidden jjfan@example.org 2025-02-28 20:50:05 e4d831d
+○  lnvvtrzo/2 hidden jjfan@example.org 2025-02-28 20:50:05 e4d831d
    (no description set)
    -- operation 0418a5aa94b5 snapshot working copy
    diff --git a/file b/file
@@ -429,22 +431,25 @@ First, we create a new empty child commit on top of `b80`:
 ```console
 $ jj new b80 -m "featureB"
 Working copy  (@) now at: pvnrkl 47171aa (empty) featureB
-Parent commit (@-)      : lnvvtr?? b8004ab featureA
+Parent commit (@-)      : lnvvtr/1 b8004ab featureA
 ```
 
-Notice the change ID has "??" appended to it. This indicates that change ID
-`lnvvtr` is now [divergent][glossary_divergence]: There are two visible commits
-with the same change ID (commit `b8004ab` and `31a347e0`). This is okay and will
-be resolved in the next steps.
+There are now two visible commits with change ID `lnvvtr` (commit `b8004ab`
+and `31a347e0`), so we call these [divergent][glossary_divergence]. Similarly
+to hidden commits, divergent commits also require a
+[change offset][glossary_change_offset] when using the change ID to refer to
+them, so you can see that `b8004ab` is still shown as `lnvvtr/1` in the output.
+This temporary divergence is okay and will be resolved in the next steps.
 
 [glossary_divergence]: glossary.md#divergent-change
+[glossary_change_offset]: glossary.md#change-offset
 
 Next, restore the contents of `31a347e0` into the working copy:
 
 ```console
 $ jj restore --from 31a347e0
 Working copy  (@) now at: pvnrkl 468104c featureB
-Parent commit (@-)      : lnvvtr?? b8004ea featureA
+Parent commit (@-)      : lnvvtr/1 b8004ea featureA
 $ cat file
 Done with feature A
 Working on feature B
@@ -547,7 +552,7 @@ with something like `jj desc -m "Revert the merge of D into B`. Now, commit `@`
 undoes the merge of `D` into  `B`. If necessary, you can now rebase it
 elsewhere, e.g. `jj rebase -r @ -o main`.
 
-### How do I deal with divergent changes ('??' after the [change ID])?
+### How do I deal with divergent changes?
 
 See: [Handling divergent commits](guides/divergence.md).
 

docs/glossary.md

@@ -116,8 +116,8 @@ call that a [divergent change](#divergent-change).
 ## Divergent change
 
 A divergent change is a [change](#change) that has more than one
-[visible commit](#visible-commits). These changes are displayed with a `??`
-after their change ID.
+[visible commit](#visible-commits). These changes are displayed with a
+[change offset](#change-offset) after their change ID.
 
 ## Head
 

docs/guides/divergence.md

@@ -5,11 +5,11 @@
 A [divergent change] occurs when multiple [visible commits] have the same change
 ID.
 
-These changes are displayed with a `??` after their change ID:
+These changes are displayed with a [change offset] after their change ID:
 
 ```shell
 $ jj log
-@  mzvwutvl?? test.user@example.com 2001-02-03 08:05:12 29d07a2d
+@  mzvwutvl/0 test.user@example.com 2001-02-03 08:05:12 29d07a2d divergent
 │  a divergent change
 ```
 
@@ -48,6 +48,7 @@ change, creating two visible successors. This can happen when:
 
 [divergent change]: ../glossary.md#divergent-change
 [visible commits]: ../glossary.md#visible-commits
+[change offset]: ../glossary.md#change-offset
 
 ## How do I resolve divergent changes?
 
@@ -55,8 +56,9 @@ When you encounter divergent changes, you have several strategies to choose
 from. The best approach depends on whether you want to keep the content from one
 commit, both commits, or merge them together.
 
-Note that revsets must refer to the divergent commit using its commit ID since
-the change ID is ambiguous.
+Note that revsets must refer to the divergent commit either using its commit ID
+or using its change ID with a [change offset] like `/0` or `/1` as shown in the
+log, since the change ID is ambiguous by itself.
 
 ### Strategy 1: Abandon one of the commits
 
@@ -64,7 +66,7 @@ If one of the divergent commits is clearly obsolete or incorrect, simply abandon
 it:
 
 ```shell
-# Abandon the unwanted commit using its commit ID
+# Abandon the unwanted commit using its commit ID (or change ID with offset)
 jj abandon <unwanted-commit-id>
 
 # You can abandon several at once with:
@@ -104,4 +106,4 @@ you can leave it as-is. If both commits are part of immutable history, this may
 be your only option.
 
 However, it can be inconvenient since you cannot refer to divergent changes
-unambiguously using their change ID.
+unambiguously using their change ID alone.