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. 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.

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.

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

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 a future version, 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

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

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

@@ -21,7 +21,6 @@ This document contains the help content for the `jj` command-line program.
 * [`jj branch track`↴](#jj-branch-track)
 * [`jj branch untrack`↴](#jj-branch-untrack)
 * [`jj cat`↴](#jj-cat)
-* [`jj checkout`↴](#jj-checkout)
 * [`jj chmod`↴](#jj-chmod)
 * [`jj commit`↴](#jj-commit)
 * [`jj config`↴](#jj-config)
@@ -105,7 +104,6 @@ To get started, see the tutorial at https://github.com/martinvonz/jj/blob/main/d
 * `backout` — Apply the reverse of a revision on top of another revision
 * `branch` — Manage branches
 * `cat` — Print contents of a file in a revision
-* `checkout` — Create a new, empty change and edit it in the working copy
 * `chmod` — Sets or removes the executable bit for paths in the repo
 * `commit` — Update the description and create a new change on top
 * `config` — Manage config options
@@ -387,28 +385,6 @@ Print contents of a file in a revision
 
 
 
-## `jj checkout`
-
-Create a new, empty change and edit it in the working copy
-
-For more information, see https://github.com/martinvonz/jj/blob/main/docs/working-copy.md.
-
-**Usage:** `jj checkout [OPTIONS] <REVISION>`
-
-###### **Arguments:**
-
-* `<REVISION>` — The revision to update to
-
-###### **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
-
-
-
 ## `jj chmod`
 
 Sets or removes the executable bit for paths in the repo

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 a future version, 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 a future version, 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 a future version, 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 a future version, 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 a future version, and this will be a hard error
     Error: Revset "none()" didn't resolve to any revisions
     "###);
 }

cli/tests/test_git_colocated.rs

@@ -127,7 +127,7 @@ fn test_git_colocated_unborn_branch() {
 
     // Stage some change, and check out root. This shouldn't clobber the HEAD.
     add_file_to_index("file0", "");
-    let (stdout, stderr) = test_env.jj_cmd_ok(&workspace_root, &["checkout", "root()"]);
+    let (stdout, stderr) = test_env.jj_cmd_ok(&workspace_root, &["new", "root()"]);
     insta::assert_snapshot!(stdout, @"");
     insta::assert_snapshot!(stderr, @r###"
     Working copy now at: kkmpptxz fcdbbd73 (empty) (no description set)
@@ -188,7 +188,7 @@ fn test_git_colocated_unborn_branch() {
     // Stage some change, and check out root again. This should unset the HEAD.
     // https://github.com/martinvonz/jj/issues/1495
     add_file_to_index("file2", "");
-    let (stdout, stderr) = test_env.jj_cmd_ok(&workspace_root, &["checkout", "root()"]);
+    let (stdout, stderr) = test_env.jj_cmd_ok(&workspace_root, &["new", "root()"]);
     insta::assert_snapshot!(stdout, @"");
     insta::assert_snapshot!(stderr, @r###"
     Working copy now at: znkkpsqq 10dd328b (empty) (no description set)

docs/git-comparison.md

@@ -234,7 +234,7 @@ parent.
     </tr>
     <tr>
       <td>Start working on a new change based on the &lt;main&gt; branch</td>
-      <td><code>jj co main</code></td>
+      <td><code>jj new main</code></td>
       <td><code>git switch -c topic main</code> or
         <code>git checkout -b topic main</code> (may need to stash or commit
         first)</td>

docs/tutorial.md

@@ -91,9 +91,7 @@ stayed the same. Each change to the working-copy commit amends the previous
 version. So how do we tell Jujutsu that we are done amending the current change
 and want to start working on a new one? That is what `jj new` is for. That will
 create a new commit on top of your current working-copy commit. The new commit
-is for the working-copy changes. For familiarity for user coming from other
-VCSs, there is also a `jj checkout/co` command, which is practically a synonym
-for `jj new` (you can specify a destination for `jj new` as well).
+is for the working-copy changes.
 
 So, let's say we're now done with this change, so we create a new change:
 
@@ -116,10 +114,10 @@ very similar to `git commit --amend`, and `jj amend` is in fact an alias for
 
 Alternatively, we can use `jj edit <commit>` to resume editing a commit in the
 working copy. Any further changes in the working copy will then amend the
-commit. Whether you choose to checkout-and-squash or to edit typically depends
-on how done you are with the change; if the change is almost done, it makes
-sense to use `jj checkout` so you can easily review your adjustments with
-`jj diff` before running `jj squash`. 
+commit. Whether you choose to create a new change and squash, or to edit,
+typically depends on how done you are with the change; if the change is almost
+done, it makes sense to use `jj new` so you can easily review your adjustments
+with `jj diff` before running `jj squash`. 
 
 ## The log command and "revsets"