undo/redo cli docs: add details about new behavior

I considered adding more details, but ultimately decided to err on the
side of brevity. We could later write a short doc detailing the behavior
(see the comments in the source) and point the CLI docs to it.

For now, I tried to explain the smallest mental model the users should
have in mind to feel comfortable with these commands.

Since `jj redo` is the command that really makes the notion of an "undo
stack" tick, I only mentioned that notion in there.

Follows up on #7293 and #7277

Author: ilyagr

cli/src/commands/redo.rs

@@ -27,7 +27,13 @@ use crate::ui::Ui;
 
 /// Redo the most recently undone operation
 ///
-/// This is the natural counterpart of `jj undo`.
+/// This is the natural counterpart of `jj undo`. Repeated invocations of `jj
+/// undo` and `jj redo` act similarly to Undo/Redo commands in a text editor.
+///
+/// Use `jj op log` to visualize the log of past operations, including a
+/// detailed description of any past undo/redo operations. See also `jj op
+/// restore` to explicitly restore an older operation by its id (available in
+/// the operation log).
 #[derive(clap::Args, Clone, Debug)]
 pub struct RedoArgs {}
 

cli/src/commands/undo.rs

@@ -31,9 +31,17 @@ use crate::ui::Ui;
 
 /// Undo the last operation
 ///
-/// This undoes the last operation by restoring its parent operation.
+/// If used once after a normal (non-`undo`) operation, this will undo that last
+/// operation by restoring its parent. If `jj undo` is used repeatedly, it will
+/// restore increasingly older operations, going further back into the past.
 ///
-/// There is also a matching `jj redo` command.
+/// There is also a complementary `jj redo` command that would instead move in
+/// the direction of the future after one or more `jj undo`s.
+///
+/// Use `jj op log` to visualize the log of past operations, including a
+/// detailed description of any past undo/redo operations. See also `jj op
+/// restore` to explicitly restore an older operation by its id (available in
+/// the operation log).
 #[derive(clap::Args, Clone, Debug)]
 pub struct UndoArgs {
     /// (deprecated, use `jj op revert <operation>`)

cli/tests/[email protected]

@@ -2305,7 +2305,9 @@ J           J
 
 Redo the most recently undone operation
 
-This is the natural counterpart of `jj undo`.
+This is the natural counterpart of `jj undo`. Repeated invocations of `jj undo` and `jj redo` act similarly to Undo/Redo commands in a text editor.
+
+Use `jj op log` to visualize the log of past operations, including a detailed description of any past undo/redo operations. See also `jj op restore` to explicitly restore an older operation by its id (available in the operation log).
 
 **Usage:** `jj redo`
 
@@ -2710,9 +2712,11 @@ Modify the metadata of a revision without changing its content
 
 Undo the last operation
 
-This undoes the last operation by restoring its parent operation.
+If used once after a normal (non-`undo`) operation, this will undo that last operation by restoring its parent. If `jj undo` is used repeatedly, it will restore increasingly older operations, going further back into the past.
+
+There is also a complementary `jj redo` command that would instead move in the direction of the future after one or more `jj undo`s.
 
-There is also a matching `jj redo` command.
+Use `jj op log` to visualize the log of past operations, including a detailed description of any past undo/redo operations. See also `jj op restore` to explicitly restore an older operation by its id (available in the operation log).
 
 **Usage:** `jj undo [OPERATION]`