Merge branch 'jc/usage-stdin'
authorJunio C Hamano <gitster@pobox.com>
Mon, 26 Oct 2015 22:55:17 +0000 (15:55 -0700)
committerJunio C Hamano <gitster@pobox.com>
Mon, 26 Oct 2015 22:55:17 +0000 (15:55 -0700)
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

25 files changed:
Documentation/git-cat-file.txt
Documentation/git-check-attr.txt
Documentation/git-check-ignore.txt
Documentation/git-commit-tree.txt
Documentation/git-fmt-merge-msg.txt
Documentation/git-get-tar-commit-id.txt
Documentation/git-hash-object.txt
Documentation/git-mktag.txt
Documentation/git-patch-id.txt
Documentation/git-show-index.txt
Documentation/git-show-ref.txt
Documentation/git-stripspace.txt
Documentation/git-unpack-objects.txt
builtin/cat-file.c
builtin/check-attr.c
builtin/check-ignore.c
builtin/commit-tree.c
builtin/get-tar-commit-id.c
builtin/hash-object.c
builtin/mktag.c
builtin/patch-id.c
builtin/show-ref.c
builtin/stripspace.c
builtin/unpack-objects.c
show-index.c
index 3105fc07205ac19805a753603940f9add612d4ae..eb3d6945a9e508c9a1d0af63e838a627311631bc 100644 (file)
@@ -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
 -----------
index 00e2aa2df259d449602f59cbec33599346ebd8a0..aa3b2bf2fcf764ca22f44bcfc081afd4e09328bb 100644 (file)
@@ -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.
index e35cd0489b6961a5322ea49eeb769bbfb883070e..59531abba481c4788357fc07342fcc7672727fbf 100644 (file)
@@ -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
index a0b5457304008cec1cf728e5ac168c5f547173eb..48c33d7ed7323c7fc4776ffeb98aad9b41b23744 100644 (file)
@@ -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>
 
index 55a9a4b93a2cba2d1d760b3529f1604b61359004..6526b178e87f9cbf1c2032bd63023295cf1d190e 100644 (file)
@@ -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]
index 1e2a20dd265c2c41aef0ea66ca9831321d951d5c..ac44d85b0b5c7f12a2d5473b3be0b0e4511cf58f 100644 (file)
@@ -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.
 
index 0c75f3b610678d9a6811ac73d208cabd706b2276..814e74406ae4fb6ac68213df1f7e8e0192d1dbaf 100644 (file)
@@ -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
index 3ca158b05e2792de404c9f0622bf4eb41af6b5e9..fa6a7561236f70808994cf63c37b400b6e337318 100644 (file)
@@ -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>
index 31efc587ee694da6885ed1ce9d1a4c1419808397..cf71fba1c0a9c18ea6428ab49820cb9e707608c6 100644 (file)
@@ -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
index fbdc8adae5b10a8ed88883647d2f0ccc3636cddc..a8a9509e0eb0bb416ce0a32f76c964a505da8f61 100644 (file)
@@ -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
index 2a6f89b235f10ea6d41047a2a42a133531ea3cab..3a324519842bd709a8ad440905fb9a9e7eaa889d 100644 (file)
@@ -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.
index 60328d5d08d43d31dd80e14b07fe75257a1f4446..2438f76da05ebf013103a08962d634c4baa9ea15 100644 (file)
@@ -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:
 
index 07d432988f249d7439ae56699496da97b7d6f828..3e887d16109c48f4f906d8a7c5c0c860bbd6123d 100644 (file)
@@ -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
index 07baad1e59c1977e5fce04d4c7288f8263947f4e..c0fd8dbb1c1bed55f541569e0c13cc865c39ec4f 100644 (file)
@@ -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
 };
 
index 21d2bedcc930ab216f2a55ec90ba188b2b66dfce..265c9ba02264d29eb3f63f1a8264c9fe7e642332 100644 (file)
@@ -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
 };
 
index dc8d97c56c60991ec5c1b5cc9eb6e20a76e5e405..43f361797ac73b64c79bb163cbb38baf78981fc9 100644 (file)
@@ -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
 };
 
index 25aa2cdef3557c67a9482492a4d0294bc7b89b04..8747c0f2fbe6426b97571bd29df0892efd1fa810 100644 (file)
@@ -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;
 
index 6f4147ad02b98de298fb054f38fab8e6d10e7335..e21c5416cd478eab3b0dddcba5ca9eeefad83d34 100644 (file)
@@ -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)
index 07fef3cc6b832c257bd3256dc6fff3d4c51760d9..43b098b76c0db28a93c6b1ebf1ea1131b0d67a0b 100644 (file)
@@ -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;
index 640ab64f418208842ae3901ce37ac8918740037e..031b750f068dea5e1652129a5df6d684f6bca850 100644 (file)
@@ -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");
index ba34dac4d2fae9bce24932c92fcee2a4bfc0f102..366ce5a5d419649dba34f607ed3f54b6a28bd3ea 100644 (file)
@@ -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)
 {
index 131ef28e5cb5d0a08bc00a7ad99e137bdd44eb66..264c3920075952b179170b65960e47b3a5b06c61 100644 (file)
@@ -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
 };
 
index 1259ed708b6b5dd1322b6db5683cf5555f41570f..958567a0cd0f3b676f2a46a699b34a67d14f129a 100644 (file)
@@ -78,8 +78,8 @@ static void comment_lines(struct strbuf *buf)
 }
 
 static const char *usage_msg = "\n"
-"  git stripspace [-s | --strip-comments] < input\n"
-"  git stripspace [-c | --comment-lines] < input";
+"  git stripspace [-s | --strip-comments]\n"
+"  git stripspace [-c | --comment-lines]";
 
 int cmd_stripspace(int argc, const char **argv, const char *prefix)
 {
index 7cc086f5f2fb4c4aa9a24a6b676f1bd6626f1b69..7c3e79c48d68251f8af94d91ef51d22567c53c07 100644 (file)
@@ -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];
index 5a9eed7fd858b6f2e454421d68e884a21acb7a23..d9e4903fed24f5916962f8d315eb680f9b4013ff 100644 (file)
@@ -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)
 {