From 0070d887e876f48264f282d65136192f2d9b5412 Mon Sep 17 00:00:00 2001
From: Martin von Zweigbergk <martinvonz@google.com>
Date: Fri, 8 Mar 2024 09:06:06 -0800
Subject: [PATCH] log: add some documentation

The `jj log` command had basically no documentation. Let's at least
start adding some.
---
 cli/src/commands/log.rs          | 8 ++++++--
 cli/tests/cli-reference@.md.snap | 8 +++++---
 2 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/cli/src/commands/log.rs b/cli/src/commands/log.rs
index 8bf661fff1..cb9656d2a1 100644
--- a/cli/src/commands/log.rs
+++ b/cli/src/commands/log.rs
@@ -27,14 +27,18 @@ use crate::diff_util::{self, DiffFormatArgs};
 use crate::graphlog::{get_graphlog, Edge};
 use crate::ui::Ui;
 
-/// Show commit history
+/// Show revision history
+///
+/// Renders a graphical view of the project's history, ordered with children
+/// before parents. By default, the output only includes mutable revisions,
+/// along with some additional revisions for context.
 #[derive(clap::Args, Clone, Debug)]
 pub(crate) struct LogArgs {
     /// Which revisions to show. Defaults to the `revsets.log` setting, or
     /// `@ | ancestors(immutable_heads().., 2) | trunk()` if it is not set.
     #[arg(long, short)]
     revisions: Vec<RevisionArg>,
-    /// Show commits modifying the given paths
+    /// Show revisions modifying the given paths
     #[arg(value_hint = clap::ValueHint::AnyPath)]
     paths: Vec<String>,
     /// Show revisions in the opposite order (older revisions first)
diff --git a/cli/tests/cli-reference@.md.snap b/cli/tests/cli-reference@.md.snap
index cd816acc3a..1c86959126 100644
--- a/cli/tests/cli-reference@.md.snap
+++ b/cli/tests/cli-reference@.md.snap
@@ -118,7 +118,7 @@ To get started, see the tutorial at https://github.com/martinvonz/jj/blob/main/d
 * `git` — Commands for working with the underlying Git repo
 * `init` — Create a new repo in the given directory
 * `interdiff` — Compare the changes of two commits
-* `log` — Show commit history
+* `log` — Show revision history
 * `move` — Move changes from one revision into another
 * `new` — Create a new, empty change and (by default) edit it in the working copy
 * `next` — Move the current working copy commit to the next child revision in the
@@ -1010,13 +1010,15 @@ This excludes changes from other commits by temporarily rebasing `--from` onto `
 
 ## `jj log`
 
-Show commit history
+Show revision history
+
+Renders a graphical view of the project's history, ordered with children before parents. By default, the output only includes mutable revisions, along with some additional revisions for context.
 
 **Usage:** `jj log [OPTIONS] [PATHS]...`
 
 ###### **Arguments:**
 
-* `<PATHS>` — Show commits modifying the given paths
+* `<PATHS>` — Show revisions modifying the given paths
 
 ###### **Options:**