[PATCH v4 00/10] cat-file: better usage UX & error messages

["Ævar Arnfjörð Bjarmason" <avarab@gmail.com>]

This series of patches to cat-file significantly improves the UX of
the -h output, see 08/10. For the v3 see[1], for the new usage output
see [2].

This re-roll addresses a minor formatting issue pointed out by Jiang
Xin in 7/10. I then updated 10/10 a bit to get rid of some repetition
and to reduce the diff size to the pre-image.

1. https://lore.kernel.org/git/cover-v3-00.10-00000000000-20211129T195357Z-avarab@gmail.com/
2. https://lore.kernel.org/git/patch-v4-08.10-ebc8dd0a22e-20211208T123151Z-avarab@gmail.com/

Ævar Arnfjörð Bjarmason (10):
  cat-file tests: test bad usage
  cat-file tests: test messaging on bad objects/paths
  parse-options API: add a usage_msg_optf()
  cat-file docs: fix SYNOPSIS and "-h" output
  cat-file: move "usage" variable to cmd_cat_file()
  cat-file: make --batch-all-objects a CMDMODE
  cat-file: fix remaining usage bugs
  cat-file: correct and improve usage information
  object-name.c: don't have GET_OID_ONLY_TO_DIE imply *_QUIETLY
  cat-file: use GET_OID_ONLY_TO_DIE in --(textconv|filters)

 Documentation/git-cat-file.txt |  10 +-
 builtin/cat-file.c             | 182 ++++++++++++++++++++-------------
 builtin/stash.c                |   4 +-
 cache.h                        |   1 +
 object-name.c                  |   8 +-
 parse-options.c                |  13 +++
 parse-options.h                |  10 ++
 t/t1006-cat-file.sh            |  92 +++++++++++++++++
 t/t8007-cat-file-textconv.sh   |  42 ++++++++
 9 files changed, 282 insertions(+), 80 deletions(-)

Range-diff against v3:
 1:  d77771e3ea0 =  1:  b3d8ec1697f cat-file tests: test bad usage
 2:  ab21a69864f =  2:  eb6fa584287 cat-file tests: test messaging on bad objects/paths
 3:  69ef1ae48c3 =  3:  01de6e4305f parse-options API: add a usage_msg_optf()
 4:  597bb97b90a =  4:  aa384803fef cat-file docs: fix SYNOPSIS and "-h" output
 5:  a9ea4c52222 =  5:  32365ff569b cat-file: move "usage" variable to cmd_cat_file()
 6:  fcb8331f091 =  6:  473ea3b0394 cat-file: make --batch-all-objects a CMDMODE
 7:  ad79e2afc89 !  7:  878d9052bfb cat-file: fix remaining usage bugs
    @@ builtin/cat-file.c: int cmd_cat_file(int argc, const char **argv, const char *pr
     -	}
     +	/* Option compatibility */
     +	if (force_path && !opt_cw)
    -+		usage_msg_optf(_("'%s=<%s> needs '%s' or '%s'"),
    ++		usage_msg_optf(_("'%s=<%s>' needs '%s' or '%s'"),
     +			       usage, options,
     +			       "--path", _("path|tree-ish"), "--filters",
     +			       "--textconv");
 8:  a378dd30dd0 =  8:  ebc8dd0a22e cat-file: correct and improve usage information
 9:  145c00db08c =  9:  a7447510e4b object-name.c: don't have GET_OID_ONLY_TO_DIE imply *_QUIETLY
10:  45a24f97c88 ! 10:  a658099e3e1 cat-file: use GET_OID_ONLY_TO_DIE in --(textconv|filters)
    @@ builtin/cat-file.c: static int cat_one_file(int opt, const char *exp_type, const
      	unsigned flags = OBJECT_INFO_LOOKUP_REPLACE;
     +	unsigned get_oid_flags = GET_OID_RECORD_PATH | GET_OID_ONLY_TO_DIE;
      	const char *path = force_path;
    -+	if (!path && (opt == 'w' || opt == 'c'))
    ++	const int opt_cw = (opt == 'c' || opt == 'w');
    ++	if (!path && opt_cw)
     +		get_oid_flags |= GET_OID_REQUIRE_PATH;
      
      	if (unknown_type)
    @@ object-name.c: static enum get_oid_result get_oid_with_context_1(struct reposito
      	oc->mode = S_IFINVALID;
      	strbuf_init(&oc->symlink_path, 0);
      	ret = get_oid_1(repo, name, namelen, oid, flags);
    --	if (!ret)
    -+	if (!ret) {
    -+		if (flags & GET_OID_REQUIRE_PATH)
    -+			die(_("<object>:<path> required, only <object> '%s' given"), name);
    ++	if (!ret && flags & GET_OID_REQUIRE_PATH)
    ++		die(_("<object>:<path> required, only <object> '%s' given"),
    ++		    name);
    + 	if (!ret)
      		return ret;
    -+	}
    -+
      	/*
    - 	 * tree:path --> object name of path in tree
    - 	 * :path -> object name of absolute path in index
     
      ## t/t8007-cat-file-textconv.sh ##
     @@ t/t8007-cat-file-textconv.sh: test_expect_success 'usage: <bad rev>' '
-- 
2.34.1.926.g895e15e0c0c