From 8cada3f5ba87242b06e8df83391ee5baba6cc05a Mon Sep 17 00:00:00 2001
From: Khionu Sybiern <dev@khionu.net>
Date: Thu, 7 Mar 2024 12:01:17 -0800
Subject: [PATCH] cli: update help message for `jj edit`

This change updates the language of `jj edit`'s help message to be
more clear as to the nature of the command. It also adds a
recommendation for a more idiomatic/safer workflow.
---
 cli/src/commands/edit.rs         | 7 ++++---
 cli/tests/cli-reference@.md.snap | 6 +++---
 2 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/cli/src/commands/edit.rs b/cli/src/commands/edit.rs
index 9a4aac7c650..48dd7022f12 100644
--- a/cli/src/commands/edit.rs
+++ b/cli/src/commands/edit.rs
@@ -21,10 +21,11 @@ use crate::cli_util::{CommandHelper, RevisionArg};
 use crate::command_error::CommandError;
 use crate::ui::Ui;
 
-/// Edit a commit in the working copy
+/// Sets the specified revision as the working-copy revision
 ///
-/// Puts the contents of a commit in the working copy for editing. Any changes
-/// you make in the working copy will update (amend) the commit.
+/// Note: it is generally recommended to instead to use `jj new` and `jj
+/// squash`. Creating a new revision enables being more intentional with respect
+/// to the existing revision.
 #[derive(clap::Args, Clone, Debug)]
 pub(crate) struct EditArgs {
     /// The commit to edit
diff --git a/cli/tests/cli-reference@.md.snap b/cli/tests/cli-reference@.md.snap
index b825dc6e09c..923a0f2b730 100644
--- a/cli/tests/cli-reference@.md.snap
+++ b/cli/tests/cli-reference@.md.snap
@@ -113,7 +113,7 @@ To get started, see the tutorial at https://github.com/martinvonz/jj/blob/main/d
 * `diff` — Compare file contents between two revisions
 * `diffedit` — Touch up the content changes in a revision with a diff editor
 * `duplicate` — Create a new change with the same content as an existing one
-* `edit` — Edit a commit in the working copy
+* `edit` — Sets the specified revision as the working-copy revision
 * `files` — List files in a revision
 * `git` — Commands for working with the underlying Git repo
 * `init` — Create a new repo in the given directory
@@ -707,9 +707,9 @@ Create a new change with the same content as an existing one
 
 ## `jj edit`
 
-Edit a commit in the working copy
+Sets the specified revision as the working-copy revision
 
-Puts the contents of a commit in the working copy for editing. Any changes you make in the working copy will update (amend) the commit.
+Note: it is generally recommended to instead to use `jj new` and `jj squash`. Creating a new revision enables being more intentional with respect to the existing revision.
 
 **Usage:** `jj edit <REVISION>`