cat-file: correct and improve usage information

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>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/builtin/cat-file.c b/builtin/cat-file.c
index 895292074aebc9098b5290316fdf329f969e4909..b5b130d79c123dd53c56866722d5f79bd57134ac 100644 (file)
--- 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()
        };