From: Bert Wesarg <bert.wesarg@googlemail.com>
Date: Fri, 08 Oct 2010 06:47:54 GMT
Subject: Re: [PATCH] Documentation: update-index: -z applies also to --index-info
Message-ID: <AANLkTimWOWHfLtiP8BkQ8ORMhjiyiAZm7Gn+OmQ2USfT@mail.gmail.com>
In-Reply-To: <7viq1dwg8v.fsf@alter.siamese.dyndns.org>

On Fri, Oct 8, 2010 at 04:49, Junio C Hamano <gitster@pobox.com> wrote:
> Bert Wesarg <bert.wesarg@googlemail.com> writes:
>
>> diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt
>> index 74d1d49..0999950 100644 Documentation/git-update-index.txt
>> --- a/Documentation/git-update-index.txt
>> +++ b/Documentation/git-update-index.txt
>> @@ -18,9 +18,9 @@ SYNOPSIS
>>            [--skip-worktree | --no-skip-worktree]
>>            [--ignore-submodules]
>>            [--really-refresh] [--unresolve] [--again | -g]
>> -          [--info-only] [--index-info]
>> -          [-z] [--stdin]
>> +          [--info-only]
>>            [--verbose]
>> +          [[-z] --stdin | --index-info]
>
> Hmm, this requires | to bind tighter than [] around -z, but that is a bit
> counterintuitive.
>
> Also, you can put -z much earlier, e.g. "update-index -z --add --stdin",
> and your version gives a false impression that we do not allow that.
>
> Writing it as "[-z] [--stdin | --index-info]" would be much easier to
> read, even though it won't convey that -z will be no-op unless we are
> reading from the standard input, either with --stdin or --index-info.
>
> I actually think we can easily lift the "must be at the end" limitation
> from both codepaths.
>
> Move the --stdin codepath to a separate helper like read_index_info(),
> remove the limitation, and add a new limitation that --stdin/--index-info
> can be given only once (as the reader will read thru EOF and the second
> call to the reader won't help us).  And do the reading after processing
> all the command line stuff (i.e. move read_index_info() call after the
> option parsing loop), to allow "update-index --stdin --add hello.c" to add
> new paths read from standard input and also hello.c was given from the
> command line.
>
> Wouldn't it make much more sense to spend brain cycles to write and review
> such a patch, rather than documenting an unnecessary limitation?
>
> Hmm?

As the subject suspects, the main intention was to document that -z
applies also to --index-info. The reminder is only falloff while
fixing this inconsistency in the documentation.

So, yes we should have spend more time to remove this limitation that
they need to be the last option.

I will prepare a patch which handles only the -z/--index-info
documentation issue.

Bert