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

On Fri, Oct 8, 2010 at 04:49, Junio C Hamano [off-list ref] wrote:

Bert Wesarg [off-list ref] writes:

quoted

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