Junio C Hamano wrote: > The synopsys text and the usage string of subcommands that read list nit: s/synopsys/synopsis/ [...] > +++ b/Documentation/git-cat-file.txt > @@ -10,7 +10,7 @@ SYNOPSIS > -------- > [verse] > 'git cat-file' (-t [--allow-unknown-type]| -s [--allow-unknown-type]| -e | -p | <type> | --textconv ) <object> > -'git cat-file' (--batch | --batch-check) [--follow-symlinks] < <list-of-objects> > +'git cat-file' (--batch | --batch-check) [--follow-symlinks] Makes sense. The BATCH OUTPUT section explains the input format. [...] > +++ b/Documentation/git-check-attr.txt > @@ -10,7 +10,7 @@ SYNOPSIS > -------- > [verse] > 'git check-attr' [-a | --all | attr...] [--] pathname... > -'git check-attr' --stdin [-z] [-a | --all | attr...] < <list-of-paths> > +'git check-attr' --stdin [-z] [-a | --all | attr...] > > DESCRIPTION > ----------- > @@ -28,7 +28,7 @@ OPTIONS > Consider `.gitattributes` in the index only, ignoring the working tree. > > --stdin:: > - Read file names from stdin instead of from the command-line. > + Read pathnames from stdin instead of from the command-line. Here I have to read the description of "-z" to understand that pathnames come one per line. How about Read pathnames from stdin, one per line, instead of from the command line. ? [...] > +++ b/Documentation/git-check-ignore.txt > @@ -10,7 +10,7 @@ SYNOPSIS > -------- > [verse] > 'git check-ignore' [options] pathname... > -'git check-ignore' [options] --stdin < <list-of-paths> > +'git check-ignore' [options] --stdin Likewise. Read pathnames from stdin, one per line, instead of from the command line. [...] > +++ b/Documentation/git-commit-tree.txt > @@ -9,7 +9,7 @@ git-commit-tree - Create a new commit object > SYNOPSIS > -------- > [verse] > -'git commit-tree' <tree> [(-p <parent>)...] < changelog > +'git commit-tree' <tree> [(-p <parent>)...] The DESCRIPTION explains the input --- good. [...] > +++ b/Documentation/git-fmt-merge-msg.txt > @@ -9,7 +9,7 @@ git-fmt-merge-msg - Produce a merge commit message > SYNOPSIS > -------- > [verse] > -'git fmt-merge-msg' [-m <message>] [--log[=<n>] | --no-log] <$GIT_DIR/FETCH_HEAD > +'git fmt-merge-msg' [-m <message>] [--log[=<n>] | --no-log] The input format isn't described anywhere, unless I think of looking at the "-F" option. More importantly, the expected usage isn't described anywhere. Perhaps an EXAMPLES section would help? EXAMPLE ------- -- $ git fetch origin master $ git fmt-merge-msg --log <$GIT_DIR/FETCH_HEAD -- Print a log message describing a merge of the "master" branch from the "origin" remote. > --- a/Documentation/git-get-tar-commit-id.txt > +++ b/Documentation/git-get-tar-commit-id.txt > @@ -9,17 +9,19 @@ git-get-tar-commit-id - Extract commit ID from an archive created using git-arch > SYNOPSIS > -------- > [verse] > -'git get-tar-commit-id' < <tarfile> > +'git get-tar-commit-id' Looks sensible. [...] > +Read an archive created by 'git archive' from the standard input and Perhaps 'Reads a tar archive'? Otherwise I would be tempted to pass in a zip or tgz file. [...] > +++ b/Documentation/git-hash-object.txt > @@ -10,7 +10,7 @@ SYNOPSIS > -------- > [verse] > 'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters] [--stdin [--literally]] [--] <file>... > -'git hash-object' [-t <type>] [-w] --stdin-paths [--no-filters] < <list-of-paths> > +'git hash-object' [-t <type>] [-w] --stdin-paths [--no-filters] Has the same ambiguity as the other --stdin option descriptions. Read pathnames from stdin, one per line, instead of from the command line. [...] > +++ b/Documentation/git-mktag.txt > @@ -9,7 +9,7 @@ git-mktag - Creates a tag object > -A tag signature file has a very simple fixed format: four lines of > +A tag signature file, to be fed from the standard input, has a s/from the/to this command's/ [...] > +++ b/Documentation/git-patch-id.txt > @@ -8,10 +8,12 @@ git-patch-id - Compute unique ID for a patch [...] > +Read a patch from the standard input, and compute the patch ID for it. Punctuation nit: there shouldn't be a comma before "and". [...] > +++ b/Documentation/git-show-index.txt > @@ -9,13 +9,14 @@ git-show-index - Show packed archive index > SYNOPSIS > -------- > [verse] > -'git show-index' < idx-file > +'git show-index' > > > DESCRIPTION > ----------- > -Reads given idx file for packed Git archive created with > -'git pack-objects' command, and dumps its contents. > +Read an idx file for packed Git archive created with > +'git pack-objects' command from the standard input, and > +dump its contents. Unrelated nit: this sounds like it's talking about "git archive" on first reading. Maybe: Reads the idx file generated alongside a Git packfile by 'git pack-objects' and dumps a description of the pack's contents. [...] > +++ b/Documentation/git-show-ref.txt > @@ -11,7 +11,7 @@ SYNOPSIS > 'git show-ref' [-q|--quiet] [--verify] [--head] [-d|--dereference] > [-s|--hash[=<n>]] [--abbrev[=<n>]] [--tags] > [--heads] [--] [<pattern>...] > -'git show-ref' --exclude-existing[=<pattern>] < ref-list > +'git show-ref' --exclude-existing[=<pattern>] What is the input format? Should there be a --stdin option to allow people to explicitly say they want to pass ref names (or patterns?) in stdin? [...] > +++ b/Documentation/git-stripspace.txt > +++ b/Documentation/git-unpack-objects.txt > +++ b/builtin/cat-file.c > +++ b/builtin/check-attr.c > +++ b/builtin/check-ignore.c > +++ b/builtin/commit-tree.c > +++ b/builtin/get-tar-commit-id.c > +++ b/builtin/hash-object.c > +++ b/builtin/mktag.c > +++ b/builtin/patch-id.c > +++ b/builtin/show-ref.c > +++ b/builtin/stripspace.c > +++ b/builtin/unpack-objects.c > +++ b/show-index.c Looks good. Thanks, Jonathan -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html