cli: deprecate jj merge

Summary: As discussed in Discord, on GitHub, and elsewhere, this change
deprecates the use of `jj merge` and suggests users use `jj new` exclusively
instead. `merge` isn't completely unfit as a name; but we think it obscures
the generality of `new` and we want people to use it instead.

To further drive the bit home, by default, `jj merge` is now hidden. This will
hopefully stop new users from running into it.

Signed-off-by: Austin Seipp <aseipp@pobox.com>
Change-Id: I94938aca9d3e2aa12d1394a5fbc58acce3185b56

cli/src/commands/merge.rs

@@ -24,6 +24,14 @@ pub(crate) fn cmd_merge(
     command: &CommandHelper,
     args: &new::NewArgs,
 ) -> Result<(), CommandError> {
+    writeln!(
+        ui.warning(),
+        "warning: `jj merge` is deprecated; use `jj new` instead, which is equivalent"
+    )?;
+    writeln!(
+        ui.warning(),
+        "warning: `jj merge` will be removed in a future version, and this will be a hard error"
+    )?;
     if args.revisions.len() < 2 {
         return Err(CommandError::CliError(String::from(
             "Merge requires at least two revisions",

cli/src/commands/mod.rs

@@ -104,6 +104,7 @@ enum Command {
     ///
     /// This is the same as `jj new`, except that it requires at least two
     /// arguments.
+    #[command(hide = true)]
     Merge(new::NewArgs),
     Move(r#move::MoveArgs),
     New(new::NewArgs),

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

@@ -49,7 +49,6 @@ This document contains the help content for the `jj` command-line program.
 * [`jj init`↴](#jj-init)
 * [`jj interdiff`↴](#jj-interdiff)
 * [`jj log`↴](#jj-log)
-* [`jj merge`↴](#jj-merge)
 * [`jj move`↴](#jj-move)
 * [`jj new`↴](#jj-new)
 * [`jj next`↴](#jj-next)
@@ -117,7 +116,6 @@ To get started, see the tutorial at https://github.com/martinvonz/jj/blob/main/d
 * `init` — Create a new repo in the given directory
 * `interdiff` — Compare the changes of two commits
 * `log` — Show commit history
-* `merge` — Merge work from multiple branches
 * `move` — Move changes from one revision into another
 * `new` — Create a new, empty change and (by default) edit it in the working copy
 * `next` — Move the current working copy commit to the next child revision in the
@@ -1012,52 +1010,6 @@ Show commit history
 
 
 
-## `jj merge`
-
-Merge work from multiple branches
-
-Unlike most other VCSs, `jj merge` does not implicitly include the working copy revision's parent as one of the parents of the merge; you need to explicitly list all revisions that should become parents of the merge.
-
-This is the same as `jj new`, except that it requires at least two arguments.
-
-**Usage:** `jj merge [OPTIONS] [REVISIONS]...`
-
-###### **Arguments:**
-
-* `<REVISIONS>` — Parent(s) of the new change
-
-  Default value: `@`
-
-###### **Options:**
-
-* `-r` — Ignored (but lets you pass `-r` for consistency with other commands)
-
-  Possible values: `true`, `false`
-
-* `-m`, `--message <MESSAGE>` — The change description to use
-* `-L`, `--allow-large-revsets` — Deprecated. Please prefix the revset with `all:` instead
-
-  Possible values: `true`, `false`
-
-* `--no-edit` — Do not edit the newly created change
-
-  Possible values: `true`, `false`
-
-* `--edit` — No-op flag to pair with --no-edit
-
-  Possible values: `true`, `false`
-
-* `-A`, `--insert-after` — Insert the new change between the target commit(s) and their children
-
-  Possible values: `true`, `false`
-
-* `-B`, `--insert-before` — Insert the new change between the target commit(s) and their parents
-
-  Possible values: `true`, `false`
-
-
-
-
 ## `jj move`
 
 Move changes from one revision into another

cli/tests/test_new_command.rs

@@ -123,10 +123,14 @@ fn test_new_merge() {
     // `jj merge` with less than two arguments is an error
     let stderr = test_env.jj_cmd_cli_error(&repo_path, &["merge"]);
     insta::assert_snapshot!(stderr, @r###"
+    warning: `jj merge` is deprecated; use `jj new` instead, which is equivalent
+    warning: `jj merge` will be removed in a future version, and this will be a hard error
     Error: Merge requires at least two revisions
     "###);
     let stderr = test_env.jj_cmd_cli_error(&repo_path, &["merge", "main"]);
     insta::assert_snapshot!(stderr, @r###"
+    warning: `jj merge` is deprecated; use `jj new` instead, which is equivalent
+    warning: `jj merge` will be removed in a future version, and this will be a hard error
     Error: Merge requires at least two revisions
     "###);