Merge branch 'jc/usage-stdin' into maint

gitster · gitster · commit f5f76845961f · 2015-11-03T15:32:38.000-08:00
The synopsis text and the usage string of subcommands that read
list of things from the standard input are often shown as if they
only take input from a file on a filesystem, which was misleading.

* jc/usage-stdin:
  usage: do not insist that standard input must come from a file
diff --git a/Documentation/git-cat-file.txt 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]
 
 DESCRIPTION
 -----------
diff --git a/Documentation/git-check-attr.txt 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,8 @@ 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 the standard input, one per line,
+	instead of from the command-line.
 
 -z::
 	The output format is modified to be machine-parseable.
diff --git a/Documentation/git-check-ignore.txt 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
 
 DESCRIPTION
 -----------
@@ -35,7 +35,8 @@ OPTIONS
 	for each given pathname.
 
 --stdin::
-	Read file names from stdin instead of from the command-line.
+	Read pathnames from the standard input, one per line,
+	instead of from the command-line.
 
 -z::
 	The output format is modified to be machine-parseable (see
diff --git a/Documentation/git-commit-tree.txt 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>)...]
 'git commit-tree' [(-p <parent>)...] [-S[<keyid>]] [(-m <message>)...]
 		  [(-F <file>)...] <tree>
 
diff --git a/Documentation/git-fmt-merge-msg.txt 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]
 'git fmt-merge-msg' [-m <message>] [--log[=<n>] | --no-log] -F <file>
 
 DESCRIPTION
@@ -57,6 +57,18 @@ merge.summary::
 	Synonym to `merge.log`; this is deprecated and will be removed in
 	the future.
 
+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.
+
+
 SEE ALSO
 --------
 linkgit:git-merge[1]
diff --git 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'
 
 
 DESCRIPTION
 -----------
-Acts as a filter, extracting the commit ID stored in archives created by
-'git archive'.  It reads only the first 1024 bytes of input, thus its
-runtime is not influenced by the size of <tarfile> very much.
+
+Read a tar archive created by 'git archive' from the standard input
+and extract the commit ID stored in it.  It reads only the first
+1024 bytes of input, thus its runtime is not influenced by the size
+of the tar archive very much.
 
 If no commit ID is found, 'git get-tar-commit-id' quietly exists with a
-return code of 1.  This can happen if <tarfile> had not been created
+return code of 1.  This can happen if the archive had not been created
 using 'git archive' or if the first parameter of 'git archive' had been
 a tree ID instead of a commit ID or tag.
 
diff --git a/Documentation/git-hash-object.txt 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]
 
 DESCRIPTION
 -----------
@@ -35,7 +35,8 @@ OPTIONS
 	Read the object from standard input instead of from a file.
 
 --stdin-paths::
-	Read file names from stdin instead of from the command-line.
+	Read file names from the standard input, one per line, instead
+	of from the command-line.
 
 --path::
 	Hash object as it were located at the given path. The location of
diff --git a/Documentation/git-mktag.txt b/Documentation/git-mktag.txt
@@ -9,7 +9,7 @@ git-mktag - Creates a tag object
 SYNOPSIS
 --------
 [verse]
-'git mktag' < signature_file
+'git mktag'
 
 DESCRIPTION
 -----------
@@ -20,7 +20,8 @@ The output is the new tag's <object> identifier.
 
 Tag Format
 ----------
-A tag signature file has a very simple fixed format: four lines of
+A tag signature file, to be fed to this command's standard input,
+has a very simple fixed format: four lines of
 
   object <sha1>
   type <typename>
diff --git a/Documentation/git-patch-id.txt b/Documentation/git-patch-id.txt
@@ -8,10 +8,12 @@ git-patch-id - Compute unique ID for a patch
 SYNOPSIS
 --------
 [verse]
-'git patch-id' [--stable | --unstable] < <patch>
+'git patch-id' [--stable | --unstable]
 
 DESCRIPTION
 -----------
+Read a patch from the standard input and compute the patch ID for it.
+
 A "patch ID" is nothing but a sum of SHA-1 of the file diffs associated with a
 patch, with whitespace and line numbers ignored.  As such, it's "reasonably
 stable", but at the same time also reasonably unique, i.e., two patches that
diff --git a/Documentation/git-show-index.txt 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 the idx file for a Git packfile created with
+'git pack-objects' command from the standard input, and
+dump its contents.
 
 The information it outputs is subset of what you can get from
 'git verify-pack -v'; this command only shows the packfile
diff --git a/Documentation/git-show-ref.txt 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>]
 
 DESCRIPTION
 -----------
@@ -23,8 +23,9 @@ particular ref exists.
 
 By default, shows the tags, heads, and remote refs.
 
-The --exclude-existing form is a filter that does the inverse, it shows the
-refs from stdin that don't exist in the local repository.
+The --exclude-existing form is a filter that does the inverse. It reads
+refs from stdin, one ref per line, and shows those that don't exist in
+the local repository.
 
 Use of this utility is encouraged in favor of directly accessing files under
 the `.git` directory.
diff --git a/Documentation/git-stripspace.txt b/Documentation/git-stripspace.txt
@@ -9,14 +9,15 @@ git-stripspace - Remove unnecessary whitespace
 SYNOPSIS
 --------
 [verse]
-'git stripspace' [-s | --strip-comments] < input
-'git stripspace' [-c | --comment-lines] < input
+'git stripspace' [-s | --strip-comments]
+'git stripspace' [-c | --comment-lines]
 
 DESCRIPTION
 -----------
 
-Clean the input in the manner used by Git for text such as commit
-messages, notes, tags and branch descriptions.
+Read text, such as commit messages, notes, tags and branch
+descriptions, from the standard input and clean it in the manner
+used by Git.
 
 With no arguments, this will:
 
diff --git a/Documentation/git-unpack-objects.txt b/Documentation/git-unpack-objects.txt
@@ -9,7 +9,7 @@ git-unpack-objects - Unpack objects from a packed archive
 SYNOPSIS
 --------
 [verse]
-'git unpack-objects' [-n] [-q] [-r] [--strict] < <packfile>
+'git unpack-objects' [-n] [-q] [-r] [--strict]
 
 
 DESCRIPTION
diff --git a/builtin/cat-file.c b/builtin/cat-file.c
@@ -426,7 +426,7 @@ static int batch_objects(struct batch_options *opt)
 
 static const char * const cat_file_usage[] = {
 	N_("git cat-file (-t [--allow-unknown-type]|-s [--allow-unknown-type]|-e|-p|<type>|--textconv) <object>"),
-	N_("git cat-file (--batch | --batch-check) [--follow-symlinks] < <list-of-objects>"),
+	N_("git cat-file (--batch | --batch-check) [--follow-symlinks]"),
 	NULL
 };
 
diff --git a/builtin/check-attr.c b/builtin/check-attr.c
@@ -9,7 +9,7 @@ static int cached_attrs;
 static int stdin_paths;
 static const char * const check_attr_usage[] = {
 N_("git check-attr [-a | --all | <attr>...] [--] <pathname>..."),
-N_("git check-attr --stdin [-z] [-a | --all | <attr>...] < <list-of-paths>"),
+N_("git check-attr --stdin [-z] [-a | --all | <attr>...]"),
 NULL
 };
 
diff --git a/builtin/check-ignore.c b/builtin/check-ignore.c
@@ -8,7 +8,7 @@
 static int quiet, verbose, stdin_paths, show_non_matching, no_index;
 static const char * const check_ignore_usage[] = {
 "git check-ignore [<options>] <pathname>...",
-"git check-ignore [<options>] --stdin < <list-of-paths>",
+"git check-ignore [<options>] --stdin",
 NULL
 };
 
diff --git a/builtin/commit-tree.c b/builtin/commit-tree.c
@@ -10,7 +10,7 @@
 #include "utf8.h"
 #include "gpg-interface.h"
 
-static const char commit_tree_usage[] = "git commit-tree [(-p <sha1>)...] [-S[<keyid>]] [-m <message>] [-F <file>] <sha1> <changelog";
+static const char commit_tree_usage[] = "git commit-tree [(-p <sha1>)...] [-S[<keyid>]] [-m <message>] [-F <file>] <sha1>";
 
 static const char *sign_commit;
 
diff --git a/builtin/get-tar-commit-id.c b/builtin/get-tar-commit-id.c
@@ -8,7 +8,7 @@
 #include "quote.h"
 
 static const char builtin_get_tar_commit_id_usage[] =
-"git get-tar-commit-id < <tarfile>";
+"git get-tar-commit-id";
 
 /* ustar header + extended global header content */
 #define RECORDSIZE	(512)
diff --git a/builtin/hash-object.c b/builtin/hash-object.c
@@ -78,7 +78,7 @@ int cmd_hash_object(int argc, const char **argv, const char *prefix)
 {
 	static const char * const hash_object_usage[] = {
 		N_("git hash-object [-t <type>] [-w] [--path=<file> | --no-filters] [--stdin] [--] <file>..."),
-		N_("git hash-object  --stdin-paths < <list-of-paths>"),
+		N_("git hash-object  --stdin-paths"),
 		NULL
 	};
 	const char *type = blob_type;
diff --git a/builtin/mktag.c b/builtin/mktag.c
@@ -154,7 +154,7 @@ int cmd_mktag(int argc, const char **argv, const char *prefix)
 	unsigned char result_sha1[20];
 
 	if (argc != 1)
-		usage("git mktag < signaturefile");
+		usage("git mktag");
 
 	if (strbuf_read(&buf, 0, 4096) < 0) {
 		die_errno("could not read from stdin");
diff --git a/builtin/patch-id.c b/builtin/patch-id.c
@@ -165,7 +165,7 @@ static void generate_id_list(int stable)
 	strbuf_release(&line_buf);
 }
 
-static const char patch_id_usage[] = "git patch-id [--stable | --unstable] < patch";
+static const char patch_id_usage[] = "git patch-id [--stable | --unstable]";
 
 static int git_patch_id_config(const char *var, const char *value, void *cb)
 {
diff --git a/builtin/show-ref.c b/builtin/show-ref.c
@@ -8,7 +8,7 @@
 
 static const char * const show_ref_usage[] = {
 	N_("git show-ref [-q | --quiet] [--verify] [--head] [-d | --dereference] [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags] [--heads] [--] [<pattern>...]"),
-	N_("git show-ref --exclude-existing[=<pattern>] < <ref-list>"),
+	N_("git show-ref --exclude-existing[=<pattern>]"),
 	NULL
 };
 
diff --git a/builtin/stripspace.c b/builtin/stripspace.c
@@ -14,8 +14,8 @@ static void comment_lines(struct strbuf *buf)
 }
 
 static const char * const stripspace_usage[] = {
-	N_("git stripspace [-s | --strip-comments] < input"),
-	N_("git stripspace [-c | --comment-lines] < input"),
+	N_("git stripspace [-s | --strip-comments]"),
+	N_("git stripspace [-c | --comment-lines]"),
 	NULL
 };
 
diff --git a/builtin/unpack-objects.c b/builtin/unpack-objects.c
@@ -13,7 +13,7 @@
 #include "fsck.h"
 
 static int dry_run, quiet, recover, has_errors, strict;
-static const char unpack_usage[] = "git unpack-objects [-n] [-q] [-r] [--strict] < pack-file";
+static const char unpack_usage[] = "git unpack-objects [-n] [-q] [-r] [--strict]";
 
 /* We always read in 4kB chunks. */
 static unsigned char buffer[4096];
diff --git a/show-index.c b/show-index.c
@@ -2,7 +2,7 @@
 #include "pack.h"
 
 static const char show_index_usage[] =
-"git show-index < <packed archive index>";
+"git show-index";
 
 int main(int argc, char **argv)
 {
