Documentation: explain optional arguments better
Improve the documentation of commands taking optional arguments in two ways: * Documents the behavior of '-O' (for grep) and '-S' (for commands creating commits) when used without the optional argument. * Document the syntax of these options. For the second point, the behavior is documented in gitcli(7), but it is easy for users to miss, and hard for the same user to understand why e.g. "git status -u no" does not work. Document this explicitly in the documentation of each short option having an optional argument: they are the most error prone since there is no '=' sign between the option and its argument. Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr> Reviewed-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Matthieu Moy committed
Sep 19, 2015 at 09:47 UTC
2b594bf90d84fd96f2b1fe904c1e62e391ceb4a0
9 files changed
+28
-10
Documentation/git-am.txt
+3
-1
@@ -138,7 +138,9 @@ default. You can use `--no-utf8` to override this.
138
139
-S[<keyid>]::
140
--gpg-sign[=<keyid>]::
141
- GPG-sign commits.
141
+ GPG-sign commits. The `keyid` argument is optional and
142
+ defaults to the committer identity; if specified, it must be
143
+ stuck to the option without a space.
144
145
--continue::
146
-r::
Documentation/git-cherry-pick.txt
+3
-1
@@ -103,7 +103,9 @@ effect to your index in a row.
103
104
-S[<keyid>]::
105
--gpg-sign[=<keyid>]::
106
- GPG-sign commits.
106
+ GPG-sign commits. The `keyid` argument is optional and
107
+ defaults to the committer identity; if specified, it must be
108
+ stuck to the option without a space.
109
110
--ff::
111
If the current HEAD is the same as the parent of the
Documentation/git-commit-tree.txt
+3
-1
@@ -56,7 +56,9 @@ OPTIONS
56
57
-S[<keyid>]::
58
--gpg-sign[=<keyid>]::
59
- GPG-sign commit.
59
+ GPG-sign commits. The `keyid` argument is optional and
60
+ defaults to the committer identity; if specified, it must be
61
+ stuck to the option without a space.
62
63
--no-gpg-sign::
64
Countermand `commit.gpgSign` configuration variable that is
Documentation/git-commit.txt
+3
-1
@@ -314,7 +314,9 @@ changes to tracked files.
314
315
-S[<keyid>]::
316
--gpg-sign[=<keyid>]::
317
- GPG-sign commit.
317
+ GPG-sign commits. The `keyid` argument is optional and
318
+ defaults to the committer identity; if specified, it must be
319
+ stuck to the option without a space.
320
321
--no-gpg-sign::
322
Countermand `commit.gpgSign` configuration variable that is
Documentation/git-grep.txt
+4
-1
@@ -165,7 +165,10 @@ OPTIONS
165
Open the matching files in the pager (not the output of 'grep').
166
If the pager happens to be "less" or "vi", and the user
167
specified only one pattern, the first file is positioned at
168
- the first match automatically.
168
+ the first match automatically. The `pager` argument is
169
+ optional; if specified, it must be stuck to the option
170
+ without a space. If `pager` is unspecified, the default pager
171
+ will be used (see `core.pager` in linkgit:git-config[1]).
172
173
-z::
174
--null::
Documentation/git-merge.txt
+3
-1
@@ -67,7 +67,9 @@ include::merge-options.txt[]
67
68
-S[<keyid>]::
69
--gpg-sign[=<keyid>]::
70
- GPG-sign the resulting merge commit.
70
+ GPG-sign the resulting merge commit. The `keyid` argument is
71
+ optional and defaults to the committer identity; if specified,
72
+ it must be stuck to the option without a space.
73
74
-m <msg>::
75
Set the commit message to be used for the merge commit (in
Documentation/git-rebase.txt
+3
-1
@@ -285,7 +285,9 @@ which makes little sense.
285
286
-S[<keyid>]::
287
--gpg-sign[=<keyid>]::
288
- GPG-sign commits.
288
+ GPG-sign commits. The `keyid` argument is optional and
289
+ defaults to the committer identity; if specified, it must be
290
+ stuck to the option without a space.
291
292
-q::
293
--quiet::
Documentation/git-revert.txt
+3
-1
@@ -82,7 +82,9 @@ effect to your index in a row.
82
83
-S[<keyid>]::
84
--gpg-sign[=<keyid>]::
85
- GPG-sign commits.
85
+ GPG-sign commits. The `keyid` argument is optional and
86
+ defaults to the committer identity; if specified, it must be
87
+ stuck to the option without a space.
88
89
-s::
90
--signoff::
Documentation/git-status.txt
+3
-2
@@ -53,8 +53,9 @@ OPTIONS
53
--untracked-files[=<mode>]::
54
Show untracked files.
55
+
56
-The mode parameter is optional (defaults to 'all'), and is used to
57
-specify the handling of untracked files.
56
+The mode parameter is used to specify the handling of untracked files.
57
+It is optional: it defaults to 'all', and if specified, it must be
58
+stuck to the option (e.g. `-uno`, but not `-u no`).
59
+
60
The possible options are:
61
+