From: "Ævar Arnfjörð Bjarmason" <avarab@gmail.com>
To: git@vger.kernel.org
Cc: "Junio C Hamano" <gitster@pobox.com>, "Jeff King" <peff@peff.net>,
"John Cai" <johncai86@gmail.com>,
"Sergey Organov" <sorganov@gmail.com>,
"Jiang Xin" <worldhello.net@gmail.com>,
"Ævar Arnfjörð Bjarmason" <avarab@gmail.com>
Subject: [PATCH v4 08/10] cat-file: correct and improve usage information
Date: Wed, 8 Dec 2021 13:34:21 +0100 [thread overview]
Message-ID: <patch-v4-08.10-ebc8dd0a22e-20211208T123151Z-avarab@gmail.com> (raw)
In-Reply-To: <cover-v4-00.10-00000000000-20211208T123151Z-avarab@gmail.com>
Change the usage output emitted on "git cat-file -h" to group related
options, making it clear to users which options go with which other
ones.
The new output is:
Check object existence or emit object contents
-e check if <object> exists
-p pretty-print <object> content
Emit [broken] object attributes
-t show object type (one of 'blob', 'tree', 'commit', 'tag', ...)
-s show object size
--allow-unknown-type allow -s and -t to work with broken/corrupt objects
Batch objects requested on stdin (or --batch-all-objects)
--batch[=<format>] show full <object> or <rev> contents
--batch-check[=<format>]
like --batch, but don't emit <contents>
--batch-all-objects with --batch[-check]: ignores stdin, batches all known objects
Change or optimize batch output
--buffer buffer --batch output
--follow-symlinks follow in-tree symlinks
--unordered do not order objects before emitting them
Emit object (blob or tree) with conversion or filter (stand-alone, or with batch)
--textconv run textconv on object's content
--filters run filters on object's content
--path blob|tree use a <path> for (--textconv | --filters ); Not with 'batch'
The old usage was:
<type> can be one of: blob, tree, commit, tag
-t show object type
-s show object size
-e exit with zero when there's no error
-p pretty-print object's content
--textconv for blob objects, run textconv on object's content
--filters for blob objects, run filters on object's content
--batch-all-objects show all objects with --batch or --batch-check
--path <blob> use a specific path for --textconv/--filters
--allow-unknown-type allow -s and -t to work with broken/corrupt objects
--buffer buffer --batch output
--batch[=<format>] show info and content of objects fed from the standard input
--batch-check[=<format>]
show info about objects fed from the standard input
--follow-symlinks follow in-tree symlinks (used with --batch or --batch-check)
--unordered do not order --batch-all-objects output
While shorter, I think the new one is easier to understand, as
e.g. "--allow-unknown-type" is grouped with "-t" and "-s", as it can
only be combined with those options. The same goes for "--buffer",
"--unordered" etc.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
builtin/cat-file.c | 49 +++++++++++++++++++++++++++-------------------
1 file changed, 29 insertions(+), 20 deletions(-)
diff --git a/builtin/cat-file.c b/builtin/cat-file.c
index 1087f0f4a85..e71519739a4 100644
--- a/builtin/cat-file.c
+++ b/builtin/cat-file.c
@@ -666,35 +666,44 @@ int cmd_cat_file(int argc, const char **argv, const char *prefix)
NULL
};
const struct option options[] = {
- OPT_GROUP(N_("<type> can be one of: blob, tree, commit, tag")),
- OPT_CMDMODE('t', NULL, &opt, N_("show object type"), 't'),
- OPT_CMDMODE('s', NULL, &opt, N_("show object size"), 's'),
+ /* Simple queries */
+ OPT_GROUP(N_("Check object existence or emit object contents")),
OPT_CMDMODE('e', NULL, &opt,
- N_("exit with zero when there's no error"), 'e'),
- OPT_CMDMODE('p', NULL, &opt, N_("pretty-print object's content"), 'p'),
- OPT_CMDMODE(0, "textconv", &opt,
- N_("for blob objects, run textconv on object's content"), 'c'),
- OPT_CMDMODE(0, "filters", &opt,
- N_("for blob objects, run filters on object's content"), 'w'),
- OPT_CMDMODE(0, "batch-all-objects", &opt,
- N_("show all objects with --batch or --batch-check"), 'b'),
- OPT_STRING(0, "path", &force_path, N_("blob"),
- N_("use a specific path for --textconv/--filters")),
+ N_("check if <object> exists"), 'e'),
+ OPT_CMDMODE('p', NULL, &opt, N_("pretty-print <object> content"), 'p'),
+
+ OPT_GROUP(N_("Emit [broken] object attributes")),
+ OPT_CMDMODE('t', NULL, &opt, N_("show object type (one of 'blob', 'tree', 'commit', 'tag', ...)"), 't'),
+ OPT_CMDMODE('s', NULL, &opt, N_("show object size"), 's'),
OPT_BOOL(0, "allow-unknown-type", &unknown_type,
N_("allow -s and -t to work with broken/corrupt objects")),
- OPT_BOOL(0, "buffer", &batch.buffer_output, N_("buffer --batch output")),
- OPT_CALLBACK_F(0, "batch", &batch, "format",
- N_("show info and content of objects fed from the standard input"),
+ /* Batch mode */
+ OPT_GROUP(N_("Batch objects requested on stdin (or --batch-all-objects)")),
+ OPT_CALLBACK_F(0, "batch", &batch, N_("format"),
+ N_("show full <object> or <rev> contents"),
PARSE_OPT_OPTARG | PARSE_OPT_NONEG,
batch_option_callback),
- OPT_CALLBACK_F(0, "batch-check", &batch, "format",
- N_("show info about objects fed from the standard input"),
+ OPT_CALLBACK_F(0, "batch-check", &batch, N_("format"),
+ N_("like --batch, but don't emit <contents>"),
PARSE_OPT_OPTARG | PARSE_OPT_NONEG,
batch_option_callback),
+ OPT_CMDMODE(0, "batch-all-objects", &opt,
+ N_("with --batch[-check]: ignores stdin, batches all known objects"), 'b'),
+ /* Batch-specific options */
+ OPT_GROUP(N_("Change or optimize batch output")),
+ OPT_BOOL(0, "buffer", &batch.buffer_output, N_("buffer --batch output")),
OPT_BOOL(0, "follow-symlinks", &batch.follow_symlinks,
- N_("follow in-tree symlinks (used with --batch or --batch-check)")),
+ N_("follow in-tree symlinks")),
OPT_BOOL(0, "unordered", &batch.unordered,
- N_("do not order --batch-all-objects output")),
+ N_("do not order objects before emitting them")),
+ /* Textconv options, stand-ole*/
+ OPT_GROUP(N_("Emit object (blob or tree) with conversion or filter (stand-alone, or with batch)")),
+ OPT_CMDMODE(0, "textconv", &opt,
+ N_("run textconv on object's content"), 'c'),
+ OPT_CMDMODE(0, "filters", &opt,
+ N_("run filters on object's content"), 'w'),
+ OPT_STRING(0, "path", &force_path, N_("blob|tree"),
+ N_("use a <path> for (--textconv | --filters ); Not with 'batch'")),
OPT_END()
};
--
2.34.1.926.g895e15e0c0c
next prev parent reply other threads:[~2021-12-08 12:34 UTC|newest]
Thread overview: 101+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-10-05 20:29 [PATCH 0/5] cat-file replace handling and optimization Jeff King
2021-10-05 20:30 ` [PATCH 1/5] t1006: clean up broken objects Jeff King
2021-10-05 20:31 ` [PATCH 2/5] cat-file: mention --unordered along with --batch-all-objects Jeff King
2021-10-05 21:02 ` Ævar Arnfjörð Bjarmason
2021-10-05 21:41 ` Jeff King
2021-10-06 9:02 ` Ævar Arnfjörð Bjarmason
2021-10-06 16:15 ` Jeff King
2021-10-07 10:18 ` Ævar Arnfjörð Bjarmason
2021-10-08 2:30 ` Jeff King
2021-10-08 7:54 ` Ævar Arnfjörð Bjarmason
2021-10-08 20:34 ` Junio C Hamano
2021-10-08 21:44 ` Jeff King
2021-10-08 22:04 ` Junio C Hamano
2021-11-06 21:46 ` [PATCH 00/10] cat-file: better usage UX & error messages Ævar Arnfjörð Bjarmason
2021-11-06 21:46 ` [PATCH 01/10] cat-file tests: test bad usage Ævar Arnfjörð Bjarmason
2021-11-07 1:07 ` Eric Sunshine
2021-11-06 21:46 ` [PATCH 02/10] cat-file tests: test messaging on bad objects/paths Ævar Arnfjörð Bjarmason
2021-11-06 21:46 ` [PATCH 03/10] parse-options API: add a usage_msg_optf() Ævar Arnfjörð Bjarmason
2021-11-06 21:46 ` [PATCH 04/10] cat-file docs: fix SYNOPSIS and "-h" output Ævar Arnfjörð Bjarmason
2021-11-06 21:46 ` [PATCH 05/10] cat-file: move "usage" variable to cmd_cat_file() Ævar Arnfjörð Bjarmason
2021-11-06 21:46 ` [PATCH 06/10] cat-file: make --batch-all-objects a CMDMODE Ævar Arnfjörð Bjarmason
2021-11-07 3:00 ` Eric Sunshine
2021-11-06 21:46 ` [PATCH 07/10] cat-file: fix remaining usage bugs Ævar Arnfjörð Bjarmason
2021-11-06 21:47 ` [PATCH 08/10] cat-file: correct and improve usage information Ævar Arnfjörð Bjarmason
2021-11-06 21:47 ` [PATCH 09/10] object-name.c: don't have GET_OID_ONLY_TO_DIE imply *_QUIETLY Ævar Arnfjörð Bjarmason
2021-11-07 3:05 ` Eric Sunshine
2021-11-06 21:47 ` [PATCH 10/10] cat-file: improve --(textconv|filters) disambiguation Ævar Arnfjörð Bjarmason
2021-11-12 22:19 ` [PATCH v2 00/10] cat-file: better usage UX & error messages Ævar Arnfjörð Bjarmason
2021-11-12 22:19 ` [PATCH v2 01/10] cat-file tests: test bad usage Ævar Arnfjörð Bjarmason
2021-11-12 22:20 ` [PATCH v2 02/10] cat-file tests: test messaging on bad objects/paths Ævar Arnfjörð Bjarmason
2021-11-12 22:20 ` [PATCH v2 03/10] parse-options API: add a usage_msg_optf() Ævar Arnfjörð Bjarmason
2021-11-12 22:20 ` [PATCH v2 04/10] cat-file docs: fix SYNOPSIS and "-h" output Ævar Arnfjörð Bjarmason
2021-11-12 22:20 ` [PATCH v2 05/10] cat-file: move "usage" variable to cmd_cat_file() Ævar Arnfjörð Bjarmason
2021-11-12 22:20 ` [PATCH v2 06/10] cat-file: make --batch-all-objects a CMDMODE Ævar Arnfjörð Bjarmason
2021-11-12 22:20 ` [PATCH v2 07/10] cat-file: fix remaining usage bugs Ævar Arnfjörð Bjarmason
2021-11-12 22:20 ` [PATCH v2 08/10] cat-file: correct and improve usage information Ævar Arnfjörð Bjarmason
2021-11-12 22:20 ` [PATCH v2 09/10] object-name.c: don't have GET_OID_ONLY_TO_DIE imply *_QUIETLY Ævar Arnfjörð Bjarmason
2021-11-12 22:20 ` [PATCH v2 10/10] cat-file: improve --(textconv|filters) disambiguation Ævar Arnfjörð Bjarmason
2021-11-29 19:57 ` [PATCH v3 00/10] cat-file: better usage UX & error messages Ævar Arnfjörð Bjarmason
2021-11-29 19:57 ` [PATCH v3 01/10] cat-file tests: test bad usage Ævar Arnfjörð Bjarmason
2021-11-29 19:57 ` [PATCH v3 02/10] cat-file tests: test messaging on bad objects/paths Ævar Arnfjörð Bjarmason
2021-11-29 19:57 ` [PATCH v3 03/10] parse-options API: add a usage_msg_optf() Ævar Arnfjörð Bjarmason
2021-11-29 19:57 ` [PATCH v3 04/10] cat-file docs: fix SYNOPSIS and "-h" output Ævar Arnfjörð Bjarmason
2021-11-29 19:57 ` [PATCH v3 05/10] cat-file: move "usage" variable to cmd_cat_file() Ævar Arnfjörð Bjarmason
2021-11-29 19:57 ` [PATCH v3 06/10] cat-file: make --batch-all-objects a CMDMODE Ævar Arnfjörð Bjarmason
2021-11-29 19:57 ` [PATCH v3 07/10] cat-file: fix remaining usage bugs Ævar Arnfjörð Bjarmason
2021-12-06 1:19 ` Jiang Xin
2021-11-29 19:57 ` [PATCH v3 08/10] cat-file: correct and improve usage information Ævar Arnfjörð Bjarmason
2021-11-29 19:57 ` [PATCH v3 09/10] object-name.c: don't have GET_OID_ONLY_TO_DIE imply *_QUIETLY Ævar Arnfjörð Bjarmason
2021-11-29 19:57 ` [PATCH v3 10/10] cat-file: use GET_OID_ONLY_TO_DIE in --(textconv|filters) Ævar Arnfjörð Bjarmason
2021-12-08 12:34 ` [PATCH v4 00/10] cat-file: better usage UX & error messages Ævar Arnfjörð Bjarmason
2021-12-08 12:34 ` [PATCH v4 01/10] cat-file tests: test bad usage Ævar Arnfjörð Bjarmason
2021-12-08 12:34 ` [PATCH v4 02/10] cat-file tests: test messaging on bad objects/paths Ævar Arnfjörð Bjarmason
2021-12-08 12:34 ` [PATCH v4 03/10] parse-options API: add a usage_msg_optf() Ævar Arnfjörð Bjarmason
2021-12-08 12:34 ` [PATCH v4 04/10] cat-file docs: fix SYNOPSIS and "-h" output Ævar Arnfjörð Bjarmason
2021-12-08 12:34 ` [PATCH v4 05/10] cat-file: move "usage" variable to cmd_cat_file() Ævar Arnfjörð Bjarmason
2021-12-08 12:34 ` [PATCH v4 06/10] cat-file: make --batch-all-objects a CMDMODE Ævar Arnfjörð Bjarmason
2021-12-08 12:34 ` [PATCH v4 07/10] cat-file: fix remaining usage bugs Ævar Arnfjörð Bjarmason
2021-12-20 16:00 ` John Cai
2021-12-08 12:34 ` Ævar Arnfjörð Bjarmason [this message]
2021-12-08 12:34 ` [PATCH v4 09/10] object-name.c: don't have GET_OID_ONLY_TO_DIE imply *_QUIETLY Ævar Arnfjörð Bjarmason
2021-12-08 12:34 ` [PATCH v4 10/10] cat-file: use GET_OID_ONLY_TO_DIE in --(textconv|filters) Ævar Arnfjörð Bjarmason
2021-12-22 4:12 ` [PATCH v5 00/10] cat-file: better usage UX & error messages Ævar Arnfjörð Bjarmason
2021-12-22 4:12 ` [PATCH v5 01/10] cat-file tests: test bad usage Ævar Arnfjörð Bjarmason
2021-12-22 4:12 ` [PATCH v5 02/10] cat-file tests: test messaging on bad objects/paths Ævar Arnfjörð Bjarmason
2021-12-22 4:12 ` [PATCH v5 03/10] parse-options API: add a usage_msg_optf() Ævar Arnfjörð Bjarmason
2021-12-22 4:12 ` [PATCH v5 04/10] cat-file docs: fix SYNOPSIS and "-h" output Ævar Arnfjörð Bjarmason
2021-12-22 4:12 ` [PATCH v5 05/10] cat-file: move "usage" variable to cmd_cat_file() Ævar Arnfjörð Bjarmason
2021-12-22 4:12 ` [PATCH v5 06/10] cat-file: make --batch-all-objects a CMDMODE Ævar Arnfjörð Bjarmason
2021-12-22 4:13 ` [PATCH v5 07/10] cat-file: fix remaining usage bugs Ævar Arnfjörð Bjarmason
2021-12-26 0:31 ` Junio C Hamano
2021-12-22 4:13 ` [PATCH v5 08/10] cat-file: correct and improve usage information Ævar Arnfjörð Bjarmason
2021-12-22 4:13 ` [PATCH v5 09/10] object-name.c: don't have GET_OID_ONLY_TO_DIE imply *_QUIETLY Ævar Arnfjörð Bjarmason
2021-12-22 4:13 ` [PATCH v5 10/10] cat-file: use GET_OID_ONLY_TO_DIE in --(textconv|filters) Ævar Arnfjörð Bjarmason
2021-12-28 13:28 ` [PATCH v6 00/10] cat-file: better usage UX & error messages Ævar Arnfjörð Bjarmason
2021-12-28 13:28 ` [PATCH v6 01/10] cat-file tests: test bad usage Ævar Arnfjörð Bjarmason
2021-12-28 13:28 ` [PATCH v6 02/10] cat-file tests: test messaging on bad objects/paths Ævar Arnfjörð Bjarmason
2021-12-28 13:28 ` [PATCH v6 03/10] parse-options API: add a usage_msg_optf() Ævar Arnfjörð Bjarmason
2021-12-28 13:28 ` [PATCH v6 04/10] cat-file docs: fix SYNOPSIS and "-h" output Ævar Arnfjörð Bjarmason
2021-12-28 13:28 ` [PATCH v6 05/10] cat-file: move "usage" variable to cmd_cat_file() Ævar Arnfjörð Bjarmason
2021-12-28 13:28 ` [PATCH v6 06/10] cat-file: make --batch-all-objects a CMDMODE Ævar Arnfjörð Bjarmason
2021-12-28 13:28 ` [PATCH v6 07/10] cat-file: fix remaining usage bugs Ævar Arnfjörð Bjarmason
2021-12-28 13:28 ` [PATCH v6 08/10] cat-file: correct and improve usage information Ævar Arnfjörð Bjarmason
2022-01-08 2:58 ` Jiang Xin
2022-01-10 22:08 ` [PATCH 0/2] fixups for issues in next-merged ab/cat-file Ævar Arnfjörð Bjarmason
2022-01-10 22:08 ` [PATCH 1/2] cat-file: don't whitespace-pad "(...)" in SYNOPSIS and usage output Ævar Arnfjörð Bjarmason
2022-01-10 22:08 ` [PATCH 2/2] cat-file: s/_/-/ in typo'd usage_msg_optf() message Ævar Arnfjörð Bjarmason
2022-01-10 22:20 ` [PATCH 0/2] fixups for issues in next-merged ab/cat-file Junio C Hamano
2022-01-11 15:48 ` Taylor Blau
2022-01-12 18:11 ` Junio C Hamano
2021-12-28 13:28 ` [PATCH v6 09/10] object-name.c: don't have GET_OID_ONLY_TO_DIE imply *_QUIETLY Ævar Arnfjörð Bjarmason
2021-12-28 13:28 ` [PATCH v6 10/10] cat-file: use GET_OID_ONLY_TO_DIE in --(textconv|filters) Ævar Arnfjörð Bjarmason
2021-10-05 20:36 ` [PATCH 3/5] cat-file: disable refs/replace with --batch-all-objects Jeff King
2021-10-06 20:33 ` Derrick Stolee
2021-10-07 20:48 ` Junio C Hamano
2021-10-05 20:36 ` [PATCH 4/5] cat-file: split ordered/unordered batch-all-objects callbacks Jeff King
2021-10-05 20:38 ` [PATCH 5/5] cat-file: use packed_object_info() for --batch-all-objects Jeff King
2021-10-07 20:56 ` Junio C Hamano
2021-10-08 2:35 ` Jeff King
2021-10-06 20:41 ` [PATCH 0/5] cat-file replace handling and optimization Derrick Stolee
2021-10-07 0:32 ` Jeff King
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=patch-v4-08.10-ebc8dd0a22e-20211208T123151Z-avarab@gmail.com \
--to=avarab@gmail.com \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=johncai86@gmail.com \
--cc=peff@peff.net \
--cc=sorganov@gmail.com \
--cc=worldhello.net@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).