cli: document that we create a new working-copy commit for abandoned one

When we abandon a working-copy commit, we create a new working-copy
commit on top. This behave is very useful, but it's not obvious. Let's
document it.

Thankfully, 2bbefcc (rewrite: default to not simplifying ancestor
merges) means that there are much fewer commands where we need to
document this behavior.

cli/src/commands/abandon.rs

@@ -27,6 +27,9 @@ use crate::ui::Ui;
 /// Abandon a revision, rebasing descendants onto its parent(s). The behavior is
 /// similar to `jj restore --changes-in`; the difference is that `jj abandon`
 /// gives you a new change, while `jj restore` updates the existing change.
+///
+/// If a working-copy commit gets abandoned, it will be given a new, empty
+/// commit. This is true in general; it is not specific to this command.
 #[derive(clap::Args, Clone, Debug)]
 pub(crate) struct AbandonArgs {
     /// The revision(s) to abandon

cli/src/commands/git.rs

@@ -150,6 +150,9 @@ pub struct GitInitArgs {
 }
 
 /// Fetch from a Git remote
+///
+/// If a working-copy commit gets abandoned, it will be given a new, empty
+/// commit. This is true in general; it is not specific to this command.
 #[derive(clap::Args, Clone, Debug)]
 pub struct GitFetchArgs {
     /// Fetch only some of the branches
@@ -233,6 +236,9 @@ pub struct GitPushArgs {
 }
 
 /// Update repo with changes made in the underlying Git repo
+///
+/// If a working-copy commit gets abandoned, it will be given a new, empty
+/// commit. This is true in general; it is not specific to this command.
 #[derive(clap::Args, Clone, Debug)]
 pub struct GitImportArgs {}
 

cli/src/commands/move.rs

@@ -34,6 +34,9 @@ use crate::ui::Ui;
 /// If the source became empty and both the source and destination had a
 /// non-empty description, you will be asked for the combined description. If
 /// either was empty, then the other one will be used.
+///
+/// If a working-copy commit gets abandoned, it will be given a new, empty
+/// commit. This is true in general; it is not specific to this command.
 #[derive(clap::Args, Clone, Debug)]
 #[command(group(ArgGroup::new("to_move").args(&["from", "to"]).multiple(true).required(true)))]
 pub(crate) struct MoveArgs {

cli/src/commands/rebase.rs

@@ -116,6 +116,9 @@ use crate::ui::Ui;
 /// |/         |/
 /// J          J
 /// ```
+///
+/// If a working-copy commit gets abandoned, it will be given a new, empty
+/// commit. This is true in general; it is not specific to this command.
 #[derive(clap::Args, Clone, Debug)]
 #[command(verbatim_doc_comment)]
 #[command(group(ArgGroup::new("to_rebase").args(&["branch", "source", "revision"])))]

cli/src/commands/squash.rs

@@ -31,6 +31,9 @@ use crate::ui::Ui;
 /// If the source became empty and both the source and destination had a
 /// non-empty description, you will be asked for the combined description. If
 /// either was empty, then the other one will be used.
+///
+/// If a working-copy commit gets abandoned, it will be given a new, empty
+/// commit. This is true in general; it is not specific to this command.
 #[derive(clap::Args, Clone, Debug)]
 #[command(visible_alias = "amend")]
 pub(crate) struct SquashArgs {

cli/src/commands/unsquash.rs

@@ -31,6 +31,9 @@ use crate::ui::Ui;
 /// If the source became empty and both the source and destination had a
 /// non-empty description, you will be asked for the combined description. If
 /// either was empty, then the other one will be used.
+///
+/// If a working-copy commit gets abandoned, it will be given a new, empty
+/// commit. This is true in general; it is not specific to this command.
 #[derive(clap::Args, Clone, Debug)]
 #[command(visible_alias = "unamend")]
 pub(crate) struct UnsquashArgs {

cli/tests/cli-reference@.md.snap

@@ -172,6 +172,8 @@ Abandon a revision
 
 Abandon a revision, rebasing descendants onto its parent(s). The behavior is similar to `jj restore --changes-in`; the difference is that `jj abandon` gives you a new change, while `jj restore` updates the existing change.
 
+If a working-copy commit gets abandoned, it will be given a new, empty commit. This is true in general; it is not specific to this command.
+
 **Usage:** `jj abandon [OPTIONS] [REVISIONS]...`
 
 ###### **Arguments:**
@@ -843,6 +845,8 @@ Create a new Git backed repo
 
 Fetch from a Git remote
 
+If a working-copy commit gets abandoned, it will be given a new, empty commit. This is true in general; it is not specific to this command.
+
 **Usage:** `jj git fetch [OPTIONS]`
 
 ###### **Options:**
@@ -917,6 +921,8 @@ By default, pushes any branches pointing to `remote_branches(remote=<remote>)..@
 
 Update repo with changes made in the underlying Git repo
 
+If a working-copy commit gets abandoned, it will be given a new, empty commit. This is true in general; it is not specific to this command.
+
 **Usage:** `jj git import`
 
 
@@ -1052,6 +1058,8 @@ Use `--interactive` to move only part of the source revision into the destinatio
 
 If the source became empty and both the source and destination had a non-empty description, you will be asked for the combined description. If either was empty, then the other one will be used.
 
+If a working-copy commit gets abandoned, it will be given a new, empty commit. This is true in general; it is not specific to this command.
+
 **Usage:** `jj move [OPTIONS] <--from <FROM>|--to <TO>> [PATHS]...`
 
 ###### **Arguments:**
@@ -1453,6 +1461,9 @@ M          L'
 J          J
 ```
 
+If a working-copy commit gets abandoned, it will be given a new, empty
+commit. This is true in general; it is not specific to this command.
+
 **Usage:** `jj rebase [OPTIONS] --destination <DESTINATION>`
 
 ###### **Options:**
@@ -1664,6 +1675,8 @@ After moving the changes into the parent, the child revision will have the same
 
 If the source became empty and both the source and destination had a non-empty description, you will be asked for the combined description. If either was empty, then the other one will be used.
 
+If a working-copy commit gets abandoned, it will be given a new, empty commit. This is true in general; it is not specific to this command.
+
 **Usage:** `jj squash [OPTIONS] [PATHS]...`
 
 ###### **Arguments:**
@@ -1854,6 +1867,8 @@ After moving the changes out of the parent, the child revision will have the sam
 
 If the source became empty and both the source and destination had a non-empty description, you will be asked for the combined description. If either was empty, then the other one will be used.
 
+If a working-copy commit gets abandoned, it will be given a new, empty commit. This is true in general; it is not specific to this command.
+
 **Usage:** `jj unsquash [OPTIONS]`
 
 ###### **Options:**