From 133598dd83d8581e995b75dbfdb76bde418cf79b Mon Sep 17 00:00:00 2001 From: Austin Seipp Date: Wed, 17 Jan 2024 16:41:43 -0600 Subject: [PATCH] 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 Change-Id: I7a1adfc9168fce1f25cf5d4c4c313304769e41a1 --- CHANGELOG.md | 21 +++++++++++++++++++++ cli/src/commands/checkout.rs | 8 ++++++++ cli/src/commands/mod.rs | 1 + cli/tests/test_checkout.rs | 14 ++++++++++++++ cli/tests/test_git_colocated.rs | 4 ++++ 5 files changed, 48 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 70e8fe069b..65577f2457 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/cli/src/commands/checkout.rs b/cli/src/commands/checkout.rs index f1cb7b59a1..76e05429b2 100644 --- a/cli/src/commands/checkout.rs +++ b/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(); diff --git a/cli/src/commands/mod.rs b/cli/src/commands/mod.rs index 31a443a68b..60b9a99d3d 100644 --- a/cli/src/commands/mod.rs +++ b/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), diff --git a/cli/tests/test_checkout.rs b/cli/tests/test_checkout.rs index c184bb6a4d..724b959726 100644 --- a/cli/tests/test_checkout.rs +++ b/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 diff --git a/cli/tests/test_git_colocated.rs b/cli/tests/test_git_colocated.rs index c0dfa34851..4817baaca3 100644 --- a/cli/tests/test_git_colocated.rs +++ b/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