[PATCH] checkout: special case error messages during noop switching

From: Junio C Hamano <gitster@pobox.com>
Date: Jul 2, 2024, 20:51 UTC
Message-ID: <xmqqikxnqzz4.fsf@gitster.g>

"git checkout" ran with no branch and no pathspec behaves like switching the branch to the current branch (in other words, a no-op, except that it gives a side-effect "here are the modified paths" report). But unlike "git checkout HEAD" or "git checkout main" (when you are on the 'main' branch), the user is much less conscious that they are "switching" to the current branch.

This twists end-user expectation in a strange way. There are options (like "--ours") that make sense only when we are checking out paths out of either the tree-ish or out of the index. So the error message the command below gives

    $ git checkout --ours
    fatal: '--ours/theirs' cannot be used with switching branches

is technically correct, but because the end-user may not even be aware of the fact that the command they are issuing is about no-op branch switching [*], they may find the error confusing.

Let's refactor the code to make it easier to special case the "no-op branch switching" situation, and then customize the exact error message for "--ours/--theirs". Since it is more likely that the end-user forgot to give pathspec that is required by the option, let's make it say

    $ git checkout --ours
    fatal: '--ours/theirs' needs the paths to check out

instead.

Among the other options that are incompatible with branch switching, there may be some that benefit by having messages tweaked when a no-op branch switching is done, but I'll leave them as #leftoverbits material.

[Footnote]

 * Yes, the end-users are irrational.  When they did not give
   "--ours", they take it granted that "git checkout" gives a short
   status, e.g..

    $ git checkout
    M	builtin/checkout.c
    M	t/t7201-co.sh

   exactly as a branch switching command.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 builtin/checkout.c | 21 ++++++++++++++-------
 t/t7201-co.sh      | 13 +++++++++++++
 2 files changed, 27 insertions(+), 7 deletions(-)

diff --git a/builtin/checkout.c b/builtin/checkout.c
index 3cf44b4683..1748d68c96 100644
--- a/builtin/checkout.c
+++ b/builtin/checkout.c
@@ -1572,6 +1572,10 @@ static void die_if_switching_to_a_branch_in_use(struct checkout_opts *opts,
 static int checkout_branch(struct checkout_opts *opts,
 			   struct branch_info *new_branch_info)
 {
+	int noop_switch = (!new_branch_info->name &&
+			   !opts->new_branch &&
+			   !opts->force_detach);
+
 	if (opts->pathspec.nr)
 		die(_("paths cannot be used with switching branches"));
 
@@ -1583,9 +1587,14 @@ static int checkout_branch(struct checkout_opts *opts,
 		die(_("'%s' cannot be used with switching branches"),
 		    "--[no]-overlay");
 
-	if (opts->writeout_stage)
-		die(_("'%s' cannot be used with switching branches"),
-		    "--ours/--theirs");
+	if (opts->writeout_stage) {
+		const char *msg;
+		if (noop_switch)
+			msg = _("'%s' needs the paths to check out");
+		else
+			msg = _("'%s' cannot be used with switching branches");
+		die(msg, "--ours/--theirs");
+	}
 
 	if (opts->force && opts->merge)
 		die(_("'%s' cannot be used with '%s'"), "-f", "-m");
@@ -1612,10 +1621,8 @@ static int checkout_branch(struct checkout_opts *opts,
 		die(_("Cannot switch branch to a non-commit '%s'"),
 		    new_branch_info->name);
 
-	if (!opts->switch_branch_doing_nothing_is_ok &&
-	    !new_branch_info->name &&
-	    !opts->new_branch &&
-	    !opts->force_detach)
+	if (noop_switch &&
+	    !opts->switch_branch_doing_nothing_is_ok)
 		die(_("missing branch or commit argument"));
 
 	if (!opts->implicit_detach &&
diff --git a/t/t7201-co.sh b/t/t7201-co.sh
index 42352dc0db..793da6e64e 100755
--- a/t/t7201-co.sh
+++ b/t/t7201-co.sh
@@ -497,6 +497,19 @@ test_expect_success 'checkout unmerged stage' '
 	test ztheirside = "z$(cat file)"
 '
 
+test_expect_success 'checkout --ours is incompatible with switching' '
+	test_must_fail git checkout --ours 2>error &&
+	test_grep "needs the paths to check out" error &&
+
+	test_must_fail git checkout --ours HEAD 2>error &&
+	test_grep "cannot be used with switching" error &&
+
+	test_must_fail git checkout --ours main 2>error &&
+	test_grep "cannot be used with switching" error &&
+
+	git checkout --ours file
+'
+
 test_expect_success 'checkout path with --merge from tree-ish is a no-no' '
 	setup_conflicting_index &&
 	test_must_fail git checkout -m HEAD -- file

-- 
2.45.2-892-g51054c73d0