cli: deprecate backout command

CHANGELOG.md

···
 
 * `core.watchman.register_snapshot_trigger` has been renamed to `core.watchman.register-snapshot-trigger` for consistency with other configuration options.
 
+* `jj backout` is deprecated in favor of `jj revert`.
+
 ### New features
 
 * `jj sign` will automatically use the gpg key associated with the author's email

cli/src/commands/backout.rs

···
 /// The description of the new revisions can be customized with the
 /// `templates.backout_description` config variable.
 #[derive(clap::Args, Clone, Debug)]
+#[command(hide = true)]
 pub(crate) struct BackoutArgs {
     /// The revision(s) to apply the reverse of
     #[arg(
···
     command: &CommandHelper,
     args: &BackoutArgs,
 ) -> Result<(), CommandError> {
+    writeln!(
+        ui.warning_default(),
+        "`jj backout` is deprecated; use `jj revert` instead"
+    )?;
+    writeln!(
+        ui.warning_default(),
+        "`jj backout` will be removed in a future version, and this will be a hard error"
+    )?;
+
     let mut workspace_command = command.workspace_helper(ui)?;
     let to_back_out: Vec<_> = workspace_command
         .parse_union_revsets(ui, &args.revisions)?

cli/src/commands/mod.rs

···
 enum Command {
     Abandon(abandon::AbandonArgs),
     Absorb(absorb::AbsorbArgs),
+    // TODO: Remove in jj 0.34+
     Backout(backout::BackoutArgs),
     #[cfg(feature = "bench")]
     #[command(subcommand)]

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

···
 * [`jj`↴](#jj)
 * [`jj abandon`↴](#jj-abandon)
 * [`jj absorb`↴](#jj-absorb)
-* [`jj backout`↴](#jj-backout)
 * [`jj bookmark`↴](#jj-bookmark)
 * [`jj bookmark create`↴](#jj-bookmark-create)
 * [`jj bookmark delete`↴](#jj-bookmark-delete)
···
 
 * `abandon` — Abandon a revision
 * `absorb` — Move changes from a revision into the stack of mutable revisions
-* `backout` — Apply the reverse of given revisions on top of another revision
 * `bookmark` — Manage bookmarks [default alias: b]
 * `commit` — Update the description and create a new change on top
 * `config` — Manage config options
···
    Only ancestors of the source revision will be considered.
 
   Default value: `mutable()`
-
-
-
-## `jj backout`
-
-Apply the reverse of given revisions on top of another revision
-
-The description of the new revisions can be customized with the `templates.backout_description` config variable.
-
-**Usage:** `jj backout [OPTIONS]`
-
-###### **Options:**
-
-* `-r`, `--revisions <REVSETS>` — The revision(s) to apply the reverse of
-
-  Default value: `@`
-* `-d`, `--destination <REVSETS>` — The revision to apply the reverse changes on top of
-
-  Default value: `@`
 
 
 

cli/tests/test_backout_command.rs

···
 
     // Backout the commit
     let output = work_dir.run_jj(["backout", "-r", "@"]);
-    insta::assert_snapshot!(output, @"");
+    insta::assert_snapshot!(output, @r"
+    ------- stderr -------
+    Warning: `jj backout` is deprecated; use `jj revert` instead
+    Warning: `jj backout` will be removed in a future version, and this will be a hard error
+    [EOF]
+    ");
     insta::assert_snapshot!(get_log_output(&work_dir), @r#"
     ○  6d845ed9fb6a Back out "a"
     │
···
     // Backout the new backed-out commit
     work_dir.run_jj(["edit", "@+"]).success();
     let output = work_dir.run_jj(["backout", "-r", "@"]);
-    insta::assert_snapshot!(output, @"");
+    insta::assert_snapshot!(output, @r"
+    ------- stderr -------
+    Warning: `jj backout` is deprecated; use `jj revert` instead
+    Warning: `jj backout` will be removed in a future version, and this will be a hard error
+    [EOF]
+    ");
     insta::assert_snapshot!(get_log_output(&work_dir), @r#"
     ○  79555ea9040b Back out "Back out "a""
     │
···
 
     // Backout multiple commits
     let output = work_dir.run_jj(["backout", "-r", "b", "-r", "c", "-r", "e"]);
-    insta::assert_snapshot!(output, @"");
+    insta::assert_snapshot!(output, @r"
+    ------- stderr -------
+    Warning: `jj backout` is deprecated; use `jj revert` instead
+    Warning: `jj backout` will be removed in a future version, and this will be a hard error
+    [EOF]
+    ");
     insta::assert_snapshot!(get_log_output(&work_dir), @r#"
     ○  6504c4ded177 Back out "b"
     │
···
 
     // Verify that message of backed out commit follows the template
     let output = work_dir.run_jj(["backout", "-r", "a"]);
-    insta::assert_snapshot!(output, @"");
+    insta::assert_snapshot!(output, @r"
+    ------- stderr -------
+    Warning: `jj backout` is deprecated; use `jj revert` instead
+    Warning: `jj backout` will be removed in a future version, and this will be a hard error
+    [EOF]
+    ");
     insta::assert_snapshot!(get_log_output(&work_dir), @r#"
     ○  1db880a5204e Revert commit 2443ea76b0b1 "a"
     @  2443ea76b0b1 a