From c1920d765f859a199c3c161073967f1e3be065a7 Mon Sep 17 00:00:00 2001
From: Evan Mesterhazy <emesterhazy@google.com>
Date: Thu, 4 Apr 2024 13:04:49 -0400
Subject: [PATCH] Improve the documentation of `jj prev`

This will hopefully make it clear that `jj prev` does not
move by [OFFSET] relative to `@`, which is a misconception
that I had and I think others may also have.

I am suggesting this change as a result of the vigorous discussion in
these two issues:

- https://github.com/martinvonz/jj/issues/3426
- https://github.com/martinvonz/jj/pull/3445

We should make similar changes to `jj next` as well since
it follows similar rules.
---
 cli/src/commands/prev.rs         | 41 ++++++++++++++++---------------
 cli/tests/cli-reference@.md.snap | 42 +++++++++++++++++---------------
 2 files changed, 43 insertions(+), 40 deletions(-)

diff --git a/cli/src/commands/prev.rs b/cli/src/commands/prev.rs
index 7e756e7ae..11c84efe9 100644
--- a/cli/src/commands/prev.rs
+++ b/cli/src/commands/prev.rs
@@ -20,35 +20,36 @@ use crate::cli_util::{short_commit_hash, CommandHelper};
 use crate::command_error::{user_error, CommandError};
 use crate::commands::next::choose_commit;
 use crate::ui::Ui;
-
-/// Move the working-copy commit to the parent revision
+/// Change the working copy revision relative to the parent revision
 ///
+/// The command creates a new empty working copy revision that is the child of
+/// an ancestor `offset` revisions behind the parent of the current working
+/// copy.
 ///
-/// The command moves you to the parent in a linear fashion.
+/// For example, when the offset is 1:
 ///
 /// ```text
-/// D @  D
-/// |/   |
-/// A => A @
-/// |    |/
-/// B    B
+/// D @      D
+/// |/       |
+/// A   =>   A @
+/// |        |/
+/// B        B
 /// ```
 ///
-/// If `--edit` is passed, it will move the working copy commit
-/// directly to the parent.
+/// If `--edit` is passed, the working copy revision is changed to the parent of
+/// the current working copy revision.
 ///
 /// ```text
-/// D @  D
-/// |/   |
-/// C => @
-/// |    |
-/// B    B
-/// |    |
-/// A    A
-///
-/// If your working-copy commit already has visible children, then `--edit` is
+/// D @      D
+/// |/       |
+/// C   =>   @
+/// |        |
+/// B        B
+/// |        |
+/// A        A
+/// ```
+/// If the working copy revision already has visible children, then `--edit` is
 /// implied.
-/// ```
 // TODO(#2126): Handle multiple parents, e.g merges.
 #[derive(clap::Args, Clone, Debug)]
 #[command(verbatim_doc_comment)]
diff --git a/cli/tests/cli-reference@.md.snap b/cli/tests/cli-reference@.md.snap
index 6b0a01137..9466e5560 100644
--- a/cli/tests/cli-reference@.md.snap
+++ b/cli/tests/cli-reference@.md.snap
@@ -128,7 +128,7 @@ To get started, see the tutorial at https://github.com/martinvonz/jj/blob/main/d
 * `obslog` — Show how a change has evolved
 * `operation` — Commands for working with the operation log
 * `parallelize` — Parallelize revisions by making them siblings
-* `prev` — Move the working-copy commit to the parent revision
+* `prev` — Change the working copy revision relative to the parent revision
 * `rebase` — Move revisions to different parent(s)
 * `resolve` — Resolve a conflicted file with an external merge tool
 * `restore` — Restore paths from another revision
@@ -1385,34 +1385,36 @@ several conditions, otherwise the command will fail.
 
 ## `jj prev`
 
-Move the working-copy commit to the parent revision
+Change the working copy revision relative to the parent revision
 
+The command creates a new empty working copy revision that is the child of
+an ancestor `offset` revisions behind the parent of the current working
+copy.
 
-The command moves you to the parent in a linear fashion.
+For example, when the offset is 1:
 
 ```text
-D @  D
-|/   |
-A => A @
-|    |/
-B    B
+D @      D
+|/       |
+A   =>   A @
+|        |/
+B        B
 ```
 
-If `--edit` is passed, it will move the working copy commit
-directly to the parent.
+If `--edit` is passed, the working copy revision is changed to the parent of
+the current working copy revision.
 
 ```text
-D @  D
-|/   |
-C => @
-|    |
-B    B
-|    |
-A    A
-
-If your working-copy commit already has visible children, then `--edit` is
+D @      D
+|/       |
+C   =>   @
+|        |
+B        B
+|        |
+A        A
+```
+If the working copy revision already has visible children, then `--edit` is
 implied.
-```
 
 **Usage:** `jj prev [OPTIONS] [OFFSET]`