Re: [PATCH 1/3] doc/cat-file: allow --use-mailmap for --batch options

[Junio C Hamano <gitster@pobox.com>]

Siddharth Asthana <siddharthasthana31@gmail.com> writes:

> The command git cat-file can now use the mailmap mechanism to replace
> idents with their canonical versions for commit and tag objects. There
> are several options like `--batch`, `--batch-check` and
> `--batch-command` that can be combined with `--use-mailmap`. But, the
> documentation for `--batch`, `--batch-check` and `--batch-command`
> doesn't say so. This patch fixes that documentation.
>
> Mentored-by: Christian Couder's avatarChristian Couder <christian.couder@gmail.com>
> Mentored-by: John Cai's avatarJohn Cai <johncai86@gmail.com>
> Signed-off-by: Siddharth Asthana <siddharthasthana31@gmail.com>
> ---
>  Documentation/git-cat-file.txt | 20 +++++++++-----------
>  1 file changed, 9 insertions(+), 11 deletions(-)
>
> diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt
> index ec30b5c574..5792f21a72 100644
> --- a/Documentation/git-cat-file.txt
> +++ b/Documentation/git-cat-file.txt
> @@ -89,24 +89,22 @@ OPTIONS
>  --batch::
>  --batch=<format>::
>  	Print object information and contents for each object provided
> -	on stdin.  May not be combined with any other options or arguments
> -	except `--textconv` or `--filters`, in which case the input lines
> -	also need to specify the path, separated by whitespace.  See the
> -	section `BATCH OUTPUT` below for details.
> +	on stdin. May only be combined with `--use-mailmap`, `--textconv` or `--filters`.
> +	In the case of `--textconv` or `--filters` the input lines also need to specify
> +	the path, separated by whitespace. See the `BATCH OUTPUT` section below for details.

The above is not wrong per-se, but I suspect that phrasing it like
so

    * When used with `--textconv` or `--filters`, the input lines must
      specify the path, separated by whitespace.

    * When used with `--use-mailmap`, THIS HAPPENS.

    Cannot be used with any other options.

would be easier to extend.  The same comment applies to the other
two changes in this patch.

As you do not have any code that implements the behaviour of
`--use-mailmap` at this point in the series yet, it might be nicer
to restructure the existing text for existing options in a
preliminary preparation patch, and then add the explanation and the
implementation of `--use-mailmap` option in a separate patch.

Thanks.