Merge branch 'mm/keyid-docs' into maint

Very small number of options take a parameter that is optional
(which is not a great UI element as they can only appear at the end
of the command line).  Add notice to documentation of each and
every one of them.

* mm/keyid-docs:
Documentation: explain optional arguments better
Documentation/grep: fix documentation of -O
Documentation: use 'keyid' consistently, not 'key-id'

diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt
index dbea6e7ae9131a1e5c51dec460d58cc6deda701b..452c1feb2319a3ac47836b5039ebeba519be3c87 100644 (file)
--- a/Documentation/git-am.txt
+++ b/Documentation/git-am.txt
@@ -141,7 +141,9 @@ default.   You can use `--no-utf8` to override this.
 
 -S[<keyid>]::
 --gpg-sign[=<keyid>]::
-       GPG-sign commits.
+       GPG-sign commits. The `keyid` argument is optional and
+       defaults to the committer identity; if specified, it must be
+       stuck to the option without a space.
 
 --continue::
 -r::

diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt
index 1147c71da605c1f5779835137fb6bab5e2c349a6..77da29a474518c56c7dab23f5921aa50566506dd 100644 (file)
--- a/Documentation/git-cherry-pick.txt
+++ b/Documentation/git-cherry-pick.txt
@@ -9,7 +9,7 @@ SYNOPSIS
 --------
 [verse]
 'git cherry-pick' [--edit] [-n] [-m parent-number] [-s] [-x] [--ff]
-                 [-S[<key-id>]] <commit>...
+                 [-S[<keyid>]] <commit>...
 'git cherry-pick' --continue
 'git cherry-pick' --quit
 'git cherry-pick' --abort
@@ -101,9 +101,11 @@ effect to your index in a row.
 --signoff::
        Add Signed-off-by line at the end of the commit message.
 
--S[<key-id>]::
---gpg-sign[=<key-id>]::
-       GPG-sign commits.
+-S[<keyid>]::
+--gpg-sign[=<keyid>]::
+       GPG-sign commits. The `keyid` argument is optional and
+       defaults to the committer identity; if specified, it must be
+       stuck to the option without a space.
 
 --ff::
        If the current HEAD is the same as the parent of the

diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt
index f5f2a8d326502714299cf85d9819bb065d5af390..a0b5457304008cec1cf728e5ac168c5f547173eb 100644 (file)
--- a/Documentation/git-commit-tree.txt
+++ b/Documentation/git-commit-tree.txt
@@ -56,7 +56,9 @@ OPTIONS
 
 -S[<keyid>]::
 --gpg-sign[=<keyid>]::
-       GPG-sign commit.
+       GPG-sign commits. The `keyid` argument is optional and
+       defaults to the committer identity; if specified, it must be
+       stuck to the option without a space.
 
 --no-gpg-sign::
        Countermand `commit.gpgSign` configuration variable that is

diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index 904dafa0f7070fc438f138393a3b356542ae04d9..7f34a5b33103ed1c870f234687079badc393be77 100644 (file)
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -13,7 +13,7 @@ SYNOPSIS
           [-F <file> | -m <msg>] [--reset-author] [--allow-empty]
           [--allow-empty-message] [--no-verify] [-e] [--author=<author>]
           [--date=<date>] [--cleanup=<mode>] [--[no-]status]
-          [-i | -o] [-S[<key-id>]] [--] [<file>...]
+          [-i | -o] [-S[<keyid>]] [--] [<file>...]
 
 DESCRIPTION
 -----------
@@ -314,7 +314,9 @@ changes to tracked files.
 
 -S[<keyid>]::
 --gpg-sign[=<keyid>]::
-       GPG-sign commit.
+       GPG-sign commits. The `keyid` argument is optional and
+       defaults to the committer identity; if specified, it must be
+       stuck to the option without a space.
 
 --no-gpg-sign::
        Countermand `commit.gpgSign` configuration variable that is

diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
index 31811f16bdaac49d01d38dcdea82bb191942b1cf..4a44d6da13cb749759f9d6164b88974ba55485ab 100644 (file)
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -160,12 +160,15 @@ OPTIONS
        For better compatibility with 'git diff', `--name-only` is a
        synonym for `--files-with-matches`.
 
--O [<pager>]::
---open-files-in-pager [<pager>]::
+-O[<pager>]::
+--open-files-in-pager[=<pager>]::
        Open the matching files in the pager (not the output of 'grep').
        If the pager happens to be "less" or "vi", and the user
        specified only one pattern, the first file is positioned at
-       the first match automatically.
+       the first match automatically. The `pager` argument is
+       optional; if specified, it must be stuck to the option
+       without a space. If `pager` is unspecified, the default pager
+       will be used (see `core.pager` in linkgit:git-config[1]).
 
 -z::
 --null::

diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index a62d6729b94963787ad435c486e1dc419c776012..07f7295ec8b603fcbd907e780d4ed1109ac5b358 100644 (file)
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -10,7 +10,7 @@ SYNOPSIS
 --------
 [verse]
 'git merge' [-n] [--stat] [--no-commit] [--squash] [--[no-]edit]
-       [-s <strategy>] [-X <strategy-option>] [-S[<key-id>]]
+       [-s <strategy>] [-X <strategy-option>] [-S[<keyid>]]
        [--[no-]rerere-autoupdate] [-m <msg>] [<commit>...]
 'git merge' <msg> HEAD <commit>...
 'git merge' --abort
@@ -67,7 +67,9 @@ include::merge-options.txt[]
 
 -S[<keyid>]::
 --gpg-sign[=<keyid>]::
-       GPG-sign the resulting merge commit.
+       GPG-sign the resulting merge commit. The `keyid` argument is
+       optional and defaults to the committer identity; if specified,
+       it must be stuck to the option without a space.
 
 -m <msg>::
        Set the commit message to be used for the merge commit (in

diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index ca039546a463bee511ca3a1c7d301689fb56a412..bccfdf7fde9af8c80203f85d98030f8f38db4994 100644 (file)
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -294,7 +294,9 @@ which makes little sense.
 
 -S[<keyid>]::
 --gpg-sign[=<keyid>]::
-       GPG-sign commits.
+       GPG-sign commits. The `keyid` argument is optional and
+       defaults to the committer identity; if specified, it must be
+       stuck to the option without a space.
 
 -q::
 --quiet::

diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt
index cceb5f2f7fa0c41174215901a091158161d89bc3..b15139ffdcda488c9e2314540885965723292a48 100644 (file)
--- a/Documentation/git-revert.txt
+++ b/Documentation/git-revert.txt
@@ -8,7 +8,7 @@ git-revert - Revert some existing commits
 SYNOPSIS
 --------
 [verse]
-'git revert' [--[no-]edit] [-n] [-m parent-number] [-s] [-S[<key-id>]] <commit>...
+'git revert' [--[no-]edit] [-n] [-m parent-number] [-s] [-S[<keyid>]] <commit>...
 'git revert' --continue
 'git revert' --quit
 'git revert' --abort
@@ -80,9 +80,11 @@ more details.
 This is useful when reverting more than one commits'
 effect to your index in a row.
 
--S[<key-id>]::
---gpg-sign[=<key-id>]::
-       GPG-sign commits.
+-S[<keyid>]::
+--gpg-sign[=<keyid>]::
+       GPG-sign commits. The `keyid` argument is optional and
+       defaults to the committer identity; if specified, it must be
+       stuck to the option without a space.
 
 -s::
 --signoff::

diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
index 335f3123353482cfd708420dac3b766f181e89ff..e1e8f57cdd217b43b9b04bc54381e9b155d9cbde 100644 (file)
--- a/Documentation/git-status.txt
+++ b/Documentation/git-status.txt
@@ -53,8 +53,9 @@ OPTIONS
 --untracked-files[=<mode>]::
        Show untracked files.
 +
-The mode parameter is optional (defaults to 'all'), and is used to
-specify the handling of untracked files.
+The mode parameter is used to specify the handling of untracked files.
+It is optional: it defaults to 'all', and if specified, it must be
+stuck to the option (e.g. `-uno`, but not `-u no`).
 +
 The possible options are:
 +

diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
index 84f6496bf228454acaa04e570f7857ba1975cda4..08b4dfbf1b049a3fc3cd04edc573845e0c976a9c 100644 (file)
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@ -9,7 +9,7 @@ git-tag - Create, list, delete or verify a tag object signed with GPG
 SYNOPSIS
 --------
 [verse]
-'git tag' [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>]
+'git tag' [-a | -s | -u <keyid>] [-f] [-m <msg> | -F <file>]
        <tagname> [<commit> | <object>]
 'git tag' -d <tagname>...
 'git tag' [-n[<num>]] -l [--contains <commit>] [--points-at <object>]
@@ -24,19 +24,19 @@ to delete, list or verify tags.
 
 Unless `-f` is given, the named tag must not yet exist.
 
-If one of `-a`, `-s`, or `-u <key-id>` is passed, the command
+If one of `-a`, `-s`, or `-u <keyid>` is passed, the command
 creates a 'tag' object, and requires a tag message.  Unless
 `-m <msg>` or `-F <file>` is given, an editor is started for the user to type
 in the tag message.
 
-If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <key-id>`
+If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <keyid>`
 are absent, `-a` is implied.
 
 Otherwise just a tag reference for the SHA-1 object name of the commit object is
 created (i.e. a lightweight tag).
 
 A GnuPG signed tag object will be created when `-s` or `-u
-<key-id>` is used.  When `-u <key-id>` is not used, the
+<keyid>` is used.  When `-u <keyid>` is not used, the
 committer identity for the current user is used to find the
 GnuPG key for signing.         The configuration variable `gpg.program`
 is used to specify custom GnuPG binary.
@@ -63,8 +63,8 @@ OPTIONS
 --sign::
        Make a GPG-signed tag, using the default e-mail address's key.
 
--u <key-id>::
---local-user=<key-id>::
+-u <keyid>::
+--local-user=<keyid>::
        Make a GPG-signed tag, using the given key.
 
 -f::
@@ -125,14 +125,14 @@ This option is only applicable when listing tags without annotation lines.
        Use the given tag message (instead of prompting).
        If multiple `-m` options are given, their values are
        concatenated as separate paragraphs.
-       Implies `-a` if none of `-a`, `-s`, or `-u <key-id>`
+       Implies `-a` if none of `-a`, `-s`, or `-u <keyid>`
        is given.
 
 -F <file>::
 --file=<file>::
        Take the tag message from the given file.  Use '-' to
        read the message from the standard input.
-       Implies `-a` if none of `-a`, `-s`, or `-u <key-id>`
+       Implies `-a` if none of `-a`, `-s`, or `-u <keyid>`
        is given.
 
 --cleanup=<mode>::
@@ -166,7 +166,7 @@ it in the repository configuration as follows:
 
 -------------------------------------
 [user]
-    signingKey = <gpg-key-id>
+    signingKey = <gpg-keyid>
 -------------------------------------