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.

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

It is planned to remove `jj merge` in version 0.18, which would give a 4 month
grace period for users to adapt. After that point, the warnings will likely
remain for a long time, as there's little cost to removing it.

Signed-off-by: Austin Seipp <[email protected]>
Change-Id: I94938aca9d3e2aa12d1394a5fbc58acce3185b56

CHANGELOG.md

@@ -28,6 +28,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   **Deadline**: `jj checkout` will be deleted and become a **hard error in
   version 0.18.0**.
 
+* `jj merge` is now deprecated; use `jj new` instead.
+
+  **Rationale**: `jj merge` is functionally equivalent to `jj new`, except it
+  requires *at least* two arguments. `jj new` can create a new commit with any
+  number of parents; whether that is 1 parent — a single commit — or
+  2, or 3 parents, which would represent various merges. `jj merge` is a
+  specialization of existing functionality; it only creates "merge commits", but
+  only because "merge commit" is defined as "has at least two parents."
+
+  This makes `jj merge` functionally redundant, and also obscures the relative
+  generality of the `jj new` command, which can create a commit from any number
+  of parents. We encourage all users to adopt `jj new` for performing merges
+  instead; it is shorter, more general, and easier to remember.
+
+  `jj merge` will no longer be shown as part of `jj help`, but will still
+  function for now, emitting a warning about its deprecation.
+
+  **Deadline**: `jj merge` will be deleted and become a **hard error in
+  version 0.18.0**.
+
 ### Breaking changes
 
 ### New features

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 jj 0.18, 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

@@ -102,6 +102,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/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 jj 0.18, 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 jj 0.18, and this will be a hard error
     Error: Merge requires at least two revisions
     "###);