Re: [PATCH 06/10] cat-file: add --batch-check=<format>

> The `cat-file --batch-check` command can be used to quickly
> get information about a large number of objects. However, it
> provides a fixed set of information.
>
> This patch adds an optional <format> option to --batch-check
> to allow a caller to specify which items they are interested
> in, and in which order to output them. This is not very
> exciting for now, since we provide the same limited set that
> you could already get. However, it opens the door to adding
> new format items in the future without breaking backwards
> compatibility (or forcing callers to pay the cost to
> calculate uninteresting items).
>
> The format atom names are chosen to match their counterparts
> in for-each-ref. Though we do not (yet) share any code with
> for-each-ref's formatter, this keeps the interface as
> consistent as possible, and may help later on if the
> implementations are unified.
>
> Signed-off-by: Jeff King <peff@peff.net>
> diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt
> index 30d585a..dd5d6e4 100644
> --- a/Documentation/git-cat-file.txt
> +++ b/Documentation/git-cat-file.txt
> @@ -78,23 +82,52 @@ each object specified on stdin:
>  If <type> is specified, the raw (though uncompressed) contents of the <object>
>  will be returned.
>
> -If '--batch' is specified, output of the following form is printed for each
> -object specified on stdin:
> +BATCH OUTPUT
> +------------
> +
> +You can specify the information shown for each object by using a custom
> +`<format>`. The `<format>` is copied literally to stdout for each
> +object, with placeholders of the form `%(atom)` expanded, followed by a
> +newline. The available atoms are:
> +
> +`objectname`::
> +       The sha1 hash of the object.

> +
> +`objecttype`::
> +       The type of of the object (the same as `cat-file -t` reports).
> +
> +`objectsize`::
> +       The size, in bytes, of the object (the same as `cat-file -s`
> +       reports).
> +
> +If no format is specified, the default format is `%(objectname)
> +%(objecttype) %(objectsize)`.
> +
> +If `--batch` is specified, the object information is followed by the
> +object contents (consisting of `%(objectsize)` bytes), followed by a
> +newline.