Re: [PATCH] Documentation: update-index: -z applies also to --index-info

["Štěpán Němec" <stepnem@gmail.com>]

Bert Wesarg <bert.wesarg@googlemail.com> writes:

> Also mention, that --stdin and --index-info needs to be the last
> option supplied and indicate this in the usage string.
>
> Signed-off-by: Bert Wesarg <bert.wesarg@googlemail.com>
>
> ---
>
> We may like the usage string like this:
>
> [[-z] --stdin | --index-info]

Yeah, that'd be definitely better IMO.

Also the usage string in builtin/update-index.c should be updated to the
same effect.

There is actually at least one more problem with the current SYNOPSIS of
`update-index'. Obviously the `*' on the third line of the Asciidoc
source makes the whole `--cacheinfo' line disappear and the rest bold
(cf. e.g. the result at
<http://www.kernel.org/pub/software/scm/git/docs/git-update-index.html>).

I guess using `...' instead of the asterisks (also on the last line,
i.e. [<file>...], not [<file>]*) would both fix the problem and at the
same time make it more consistent with other man pages.

> to make it also clear, that -z applies only to --stdin or --index-only.
> ---
>  Documentation/git-update-index.txt |   14 ++++++++------
>  1 files changed, 8 insertions(+), 6 deletions(-)
>
> diff --git a/Documentation/git-update-index.txt
> b/Documentation/git-update-index.txt
> index 74d1d49..4441d7c 100644 Documentation/git-update-index.txt
> --- a/Documentation/git-update-index.txt
> +++ b/Documentation/git-update-index.txt
> @@ -18,8 +18,9 @@ SYNOPSIS
>  	     [--skip-worktree | --no-skip-worktree]
>  	     [--ignore-submodules]
>  	     [--really-refresh] [--unresolve] [--again | -g]
> -	     [--info-only] [--index-info]
> -	     [-z] [--stdin]
> +	     [--info-only]
> +	     [-z]
> +	     [--stdin] [--index-info]
>  	     [--verbose]
>  	     [--] [<file>]*

Shouldn't `--verbose' be also moved before the must-be-last options?

> @@ -72,7 +73,7 @@ OPTIONS
>  	Directly insert the specified info into the index.
>  
>  --index-info::
> -        Read index information from stdin.
> +        Read index information from stdin (Must be last option).

I'm not a native speaker myself, but I suspect "must be THE last option"
is more correct (including the lower-case `m' :-)).

>  --chmod=(+|-)x::
>          Set the execute permissions on the updated files.
> @@ -138,14 +139,15 @@ you will need to handle the situation manually.
>  --stdin::
>  	Instead of taking list of paths from the command line,
>  	read list of paths from the standard input.  Paths are
> -	separated by LF (i.e. one path per line) by default.
> +	separated by LF (i.e. one path per line) by default
> +	(Must be last option).

(same here)

>  
>  --verbose::
>          Report what is being added and removed from index.
>  
>  -z::
> -	Only meaningful with `--stdin`; paths are separated with
> -	NUL character instead of LF.
> +	Only meaningful with `--stdin` or `--index-info`; paths are
> +	separated with NUL character instead of LF.
>  
>  \--::
>  	Do not interpret any more arguments as options.

Thanks,

Štěpán