[PATCH v2] refs: avoid "too many arguments"

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 6, 2024, 17:47 UTC
Message-ID: <xmqqed71tufv.fsf_-_@gitster.g>
In-Reply-To: <20240806003539.3292562-2-gitster@pobox.com>

Running "git refs migrate master main" would fail and say "too many arguments". By reading that message, you cannot tell if you just should have given a single ref and made it "git refs migrate master", or the command refuses to take any arguments.

Instead, report that "git ref migrate" takes no arguments, which is far easier for the user to understand.

    $ git refs migrate master main
    fatal: 'git refs migrate' takes no arguments

The other side of the coin this change is covering is to remove doubts in new users' minds when we say "git refs migrate", if it is "git" command running with two "refs migrate" arguments, "git refs" command running with one "migrate" argument, or "git refs migrate" command running with no arguments.

In the same spirit, reword the existing "missing --ref-format=<format>" message and say

    $ git refs migrate
    fatal: 'git refs migrate' needs '--ref-format=<format>'

Note that we are turning two usage() calls to die() calls. The former should signal that the message given is a command line that shows the usage help of the command. If we are giving a fatal error message, we should not hesitate to use die().

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 * This is no longer a series.  I may resurrect [2,3,4/4] later, but
   they do not share any new helper routines at this moment, so they
   can stay independent patches.  Or perhaps while looking at this
   use case deeper during the review of this patch, we might come up
   with a good way to address this issue for many other scenarios
   and make a set of helper routines, in which case those other
   steps may have to become a part of series again to take advantage
   of them.

 builtin/refs.c          |  4 ++--
 t/t1460-refs-migrate.sh | 10 ++--------
 2 files changed, 4 insertions(+), 10 deletions(-)

diff --git a/builtin/refs.c b/builtin/refs.c
index 46dcd150d4..a51602f84b 100644
--- a/builtin/refs.c
+++ b/builtin/refs.c
@@ -30,9 +30,9 @@ static int cmd_refs_migrate(int argc, const char **argv, const char *prefix)
 
 	argc = parse_options(argc, argv, prefix, options, migrate_usage, 0);
 	if (argc)
-		usage(_("too many arguments"));
+		die(_("'git refs migrate' takes no arguments"));
 	if (!format_str)
-		usage(_("missing --ref-format=<format>"));
+		die(_("'git refs migrate' needs '--ref-format=<format>'"));
 
 	format = ref_storage_format_by_name(format_str);
 	if (format == REF_STORAGE_FORMAT_UNKNOWN) {
diff --git a/t/t1460-refs-migrate.sh b/t/t1460-refs-migrate.sh
index f7c0783d30..e063a98b11 100755
--- a/t/t1460-refs-migrate.sh
+++ b/t/t1460-refs-migrate.sh
@@ -31,20 +31,14 @@ test_expect_success "superfluous arguments" '
 	test_when_finished "rm -rf repo" &&
 	git init repo &&
 	test_must_fail git -C repo refs migrate foo 2>err &&
-	cat >expect <<-EOF &&
-	usage: too many arguments
-	EOF
-	test_cmp expect err
+	test_grep "takes no arguments" err
 '
 
 test_expect_success "missing ref storage format" '
 	test_when_finished "rm -rf repo" &&
 	git init repo &&
 	test_must_fail git -C repo refs migrate 2>err &&
-	cat >expect <<-EOF &&
-	usage: missing --ref-format=<format>
-	EOF
-	test_cmp expect err
+	test_grep "needs ${SQ}--ref-format=<format>${SQ}" err
 '
 
 test_expect_success "unknown ref storage format" '

Interdiff against v1:
  diff --git a/builtin/refs.c b/builtin/refs.c
  index a2aac38ceb..a51602f84b 100644
  --- a/builtin/refs.c
  +++ b/builtin/refs.c
  @@ -30,11 +30,9 @@ static int cmd_refs_migrate(int argc, const char **argv, const char *prefix)
   
   	argc = parse_options(argc, argv, prefix, options, migrate_usage, 0);
   	if (argc)
  -		usage_msg_optf(_("unknown argument: '%s'"),
  -			       migrate_usage, options,
  -			       argv[0]);
  +		die(_("'git refs migrate' takes no arguments"));
   	if (!format_str)
  -		usage(_("missing --ref-format=<format>"));
  +		die(_("'git refs migrate' needs '--ref-format=<format>'"));
   
   	format = ref_storage_format_by_name(format_str);
   	if (format == REF_STORAGE_FORMAT_UNKNOWN) {
  diff --git a/t/t1460-refs-migrate.sh b/t/t1460-refs-migrate.sh
  index b32e740001..e063a98b11 100755
  --- a/t/t1460-refs-migrate.sh
  +++ b/t/t1460-refs-migrate.sh
  @@ -31,21 +31,14 @@ test_expect_success "superfluous arguments" '
   	test_when_finished "rm -rf repo" &&
   	git init repo &&
   	test_must_fail git -C repo refs migrate foo 2>err &&
  -	{
  -		printf "fatal: unknown argument: ${SQ}foo${SQ}\n\n" &&
  -		( git -C repo refs migrate -h || : )
  -	} >expect &&
  -	test_cmp expect err
  +	test_grep "takes no arguments" err
   '
   
   test_expect_success "missing ref storage format" '
   	test_when_finished "rm -rf repo" &&
   	git init repo &&
   	test_must_fail git -C repo refs migrate 2>err &&
  -	cat >expect <<-EOF &&
  -	usage: missing --ref-format=<format>
  -	EOF
  -	test_cmp expect err
  +	test_grep "needs ${SQ}--ref-format=<format>${SQ}" err
   '
   
   test_expect_success "unknown ref storage format" '

-- 
2.46.0-235-g968ce1ce0e