From 7da170d53fd665e27067de384b3ced32bd983cbd Mon Sep 17 00:00:00 2001
From: Steve Klabnik <steve@steveklabnik.com>
Date: Fri, 5 Dec 2025 16:02:36 -0600
Subject: [PATCH] docs: mention ?? means 'divergence'

While divergence is talked about in the documentation, few places actually
mention how divergent changes are displayed. I've added such notes to the help
out put of `jj log`, the glossary, and added an example to the guide we have on
divergence.

Fixes #6365
---
 cli/src/commands/log.rs          | 5 +++++
 cli/tests/cli-reference@.md.snap | 4 ++++
 docs/glossary.md                 | 3 ++-
 docs/guides/divergence.md        | 8 ++++++++
 4 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/cli/src/commands/log.rs b/cli/src/commands/log.rs
index 093da0d49..d3f47c4e4 100644
--- a/cli/src/commands/log.rs
+++ b/cli/src/commands/log.rs
@@ -61,11 +61,16 @@ 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].
+///
 /// [Immutable revisions]:
 ///     https://docs.jj-vcs.dev/latest/config/#set-of-immutable-commits
 ///
 /// [customized]:
 ///     https://docs.jj-vcs.dev/latest/config/#node-style
+///
+/// [divergent]:
+///     https://docs.jj-vcs.dev/latest/guides/divergence/
 #[derive(clap::Args, Clone, Debug)]
 pub(crate) struct LogArgs {
     /// Which revisions to show
diff --git a/cli/tests/cli-reference@.md.snap b/cli/tests/cli-reference@.md.snap
index 00d8cf631..ce9800f14 100644
--- a/cli/tests/cli-reference@.md.snap
+++ b/cli/tests/cli-reference@.md.snap
@@ -1771,10 +1771,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].
+
 [Immutable revisions]: https://docs.jj-vcs.dev/latest/config/#set-of-immutable-commits
 
 [customized]: https://docs.jj-vcs.dev/latest/config/#node-style
 
+[divergent]: https://docs.jj-vcs.dev/latest/guides/divergence/
+
 **Usage:** `jj log [OPTIONS] [FILESETS]...`
 
 ###### **Arguments:**
diff --git a/docs/glossary.md b/docs/glossary.md
index 158392ed6..bcd176b52 100644
--- a/docs/glossary.md
+++ b/docs/glossary.md
@@ -107,7 +107,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).
+[visible commit](#visible-commits). These changes are displayed with a `??`
+after their change ID.
 
 ## Head
 
diff --git a/docs/guides/divergence.md b/docs/guides/divergence.md
index 1d2c2a3b1..5380e7b94 100644
--- a/docs/guides/divergence.md
+++ b/docs/guides/divergence.md
@@ -5,6 +5,14 @@
 A [divergent change] occurs when multiple [visible commits] have the same change
 ID.
 
+These changes are displayed with a `??` after their change ID:
+
+```shell
+$ jj log
+@  mzvwutvl?? test.user@example.com 2001-02-03 08:05:12 29d07a2d
+│  a divergent change
+```
+
 Normally, when commits are rewritten, the original version (the "predecessor")
 becomes hidden and the new commit (the "successor") is visible. Thus, only one
 commit with a given change ID is visible at a time.