cli: deprecate jj checkout

Summary: As discussed in Discord, on GitHub, and elsewhere, this change
deprecates the use of `jj checkout` and suggests users use `jj new` exclusively
instead.

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

It is planned to remove `jj checkout` 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: I7a1adfc9168fce1f25cf5d4c4c313304769e41a1

CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Deprecations
+
+* `jj checkout` is now deprecated; use `jj new` instead.
+
+  **Rationale**: `jj checkout` is functionally equivalent to `jj new`, except it
+  can only take a single argument; `jj new` can take more than one argument,
+  resulting in a merge commit with multiple parents. They are always equivalent
+  in the case of a single argument, hence `jj new` is a strict superset of
+  functionality.
+
+  More importantly, the verb `checkout` is a relic of a bygone era — the
+  days of RCS file locking, before 3-way merge — and is not a good,
+  fitting name for the functionality it provides. We encourage all users to
+  adopt `jj new` instead; it is shorter, more general, and easier to remember.
+
+  `jj checkout` will no longer be shown as part of `jj help`, but will still
+  function for now, emitting a warning about its deprecation.
+
+  **Deadline**: `jj checkout` will be deleted and become a **hard error in
+  version 0.18.0**.
+
 ### Breaking changes
 
 ### New features

cli/src/commands/checkout.rs

@@ -41,6 +41,14 @@ pub(crate) fn cmd_checkout(
     command: &CommandHelper,
     args: &CheckoutArgs,
 ) -> Result<(), CommandError> {
+    writeln!(
+        ui.warning(),
+        "warning: `jj checkout` is deprecated; use `jj new` instead, which is equivalent"
+    )?;
+    writeln!(
+        ui.warning(),
+        "warning: `jj checkout` will be removed in jj 0.18, and this will be a hard error"
+    )?;
     let mut workspace_command = command.workspace_helper(ui)?;
     let target = workspace_command.resolve_single_rev(&args.revision, ui)?;
     let mut tx = workspace_command.start_transaction();

cli/src/commands/mod.rs

@@ -74,6 +74,7 @@ enum Command {
     Branch(branch::BranchSubcommand),
     #[command(alias = "print")]
     Cat(cat::CatArgs),
+    #[command(hide = true)]
     Checkout(checkout::CheckoutArgs),
     Chmod(chmod::ChmodArgs),
     Commit(commit::CommitArgs),

cli/tests/test_checkout.rs

@@ -31,6 +31,8 @@ fn test_checkout() {
     let (stdout, stderr) = test_env.jj_cmd_ok(&repo_path, &["checkout", "@"]);
     insta::assert_snapshot!(stdout, @"");
     insta::assert_snapshot!(stderr, @r###"
+    warning: `jj checkout` is deprecated; use `jj new` instead, which is equivalent
+    warning: `jj checkout` will be removed in jj 0.18, and this will be a hard error
     Working copy now at: zsuskuln 05ce7118 (empty) (no description set)
     Parent commit      : rlvkpnrz 5c52832c (empty) second
     "###);
@@ -66,6 +68,8 @@ fn test_checkout_not_single_rev() {
 
     let stderr = test_env.jj_cmd_failure(&repo_path, &["checkout", "root()..@"]);
     insta::assert_snapshot!(stderr, @r###"
+    warning: `jj checkout` is deprecated; use `jj new` instead, which is equivalent
+    warning: `jj checkout` will be removed in jj 0.18, and this will be a hard error
     Error: Revset "root()..@" resolved to more than one revision
     Hint: The revset "root()..@" resolved to these revisions:
     royxmykx 2f859371 (empty) (no description set)
@@ -78,6 +82,8 @@ fn test_checkout_not_single_rev() {
 
     let stderr = test_env.jj_cmd_failure(&repo_path, &["checkout", "root()..@-"]);
     insta::assert_snapshot!(stderr, @r###"
+    warning: `jj checkout` is deprecated; use `jj new` instead, which is equivalent
+    warning: `jj checkout` will be removed in jj 0.18, and this will be a hard error
     Error: Revset "root()..@-" resolved to more than one revision
     Hint: The revset "root()..@-" resolved to these revisions:
     mzvwutvl 5c1afd8b (empty) fifth
@@ -89,6 +95,8 @@ fn test_checkout_not_single_rev() {
 
     let stderr = test_env.jj_cmd_failure(&repo_path, &["checkout", "@-|@--"]);
     insta::assert_snapshot!(stderr, @r###"
+    warning: `jj checkout` is deprecated; use `jj new` instead, which is equivalent
+    warning: `jj checkout` will be removed in jj 0.18, and this will be a hard error
     Error: Revset "@-|@--" resolved to more than one revision
     Hint: The revset "@-|@--" resolved to these revisions:
     mzvwutvl 5c1afd8b (empty) fifth
@@ -97,6 +105,8 @@ fn test_checkout_not_single_rev() {
 
     let stderr = test_env.jj_cmd_failure(&repo_path, &["checkout", "none()"]);
     insta::assert_snapshot!(stderr, @r###"
+    warning: `jj checkout` is deprecated; use `jj new` instead, which is equivalent
+    warning: `jj checkout` will be removed in jj 0.18, and this will be a hard error
     Error: Revset "none()" didn't resolve to any revisions
     "###);
 }
@@ -127,6 +137,8 @@ fn test_checkout_conflicting_branches() {
 
     let stderr = test_env.jj_cmd_failure(&repo_path, &["checkout", "foo"]);
     insta::assert_snapshot!(stderr, @r###"
+    warning: `jj checkout` is deprecated; use `jj new` instead, which is equivalent
+    warning: `jj checkout` will be removed in jj 0.18, and this will be a hard error
     Error: Revset "foo" resolved to more than one revision
     Hint: Branch foo resolved to multiple revisions because it's conflicted.
     It resolved to these revisions:
@@ -150,6 +162,8 @@ fn test_checkout_conflicting_change_ids() {
 
     let stderr = test_env.jj_cmd_failure(&repo_path, &["checkout", "qpvuntsm"]);
     insta::assert_snapshot!(stderr, @r###"
+    warning: `jj checkout` is deprecated; use `jj new` instead, which is equivalent
+    warning: `jj checkout` will be removed in jj 0.18, and this will be a hard error
     Error: Revset "qpvuntsm" resolved to more than one revision
     Hint: The revset "qpvuntsm" resolved to these revisions:
     qpvuntsm?? d2ae6806 (empty) two

cli/tests/test_git_colocated.rs

@@ -130,6 +130,8 @@ fn test_git_colocated_unborn_branch() {
     let (stdout, stderr) = test_env.jj_cmd_ok(&workspace_root, &["checkout", "root()"]);
     insta::assert_snapshot!(stdout, @"");
     insta::assert_snapshot!(stderr, @r###"
+    warning: `jj checkout` is deprecated; use `jj new` instead, which is equivalent
+    warning: `jj checkout` will be removed in jj 0.18, and this will be a hard error
     Working copy now at: kkmpptxz fcdbbd73 (empty) (no description set)
     Parent commit      : zzzzzzzz 00000000 (empty) (no description set)
     Added 0 files, modified 0 files, removed 1 files
@@ -191,6 +193,8 @@ fn test_git_colocated_unborn_branch() {
     let (stdout, stderr) = test_env.jj_cmd_ok(&workspace_root, &["checkout", "root()"]);
     insta::assert_snapshot!(stdout, @"");
     insta::assert_snapshot!(stderr, @r###"
+    warning: `jj checkout` is deprecated; use `jj new` instead, which is equivalent
+    warning: `jj checkout` will be removed in jj 0.18, and this will be a hard error
     Working copy now at: znkkpsqq 10dd328b (empty) (no description set)
     Parent commit      : zzzzzzzz 00000000 (empty) (no description set)
     Added 0 files, modified 0 files, removed 2 files