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

On Thu, Oct 7, 2010 at 20:33, Štěpán Němec [off-list ref] wrote:

Bert Wesarg [off-list ref] writes:

quoted

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 <redacted>

---

We may like the usage string like this:

[[-z] --stdin | --index-info]

Yeah, that'd be definitely better IMO.

Will do.

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.

I wont change it in this patch, because I can't build the html docs right now.

quoted

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?

Sure. I noticed this myself, but the patch was already in the wire.

quoted

@@ -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' :-)).

Maybe this should be in its own sentence, like the '(Implies
--remove.)' in --force-remove.

quoted

 --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)

quoted

 --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,

Thank you.

Bert

Štěpán