From: Matthieu Moy <Matthieu.Moy@imag.fr>
To: gitster@pobox.com
Cc: git@vger.kernel.org, Alastair McGowan-Douglas <altreus@altre.us>,
Jeff King <peff@peff.net>, Matthieu Moy <Matthieu.Moy@imag.fr>
Subject: [PATCH 3/3] Documentation: make explicit that optional arguments must be stuck
Date: Fri, 18 Sep 2015 17:01:50 +0200 [thread overview]
Message-ID: <1442588510-7379-4-git-send-email-Matthieu.Moy@imag.fr> (raw)
In-Reply-To: <1442588510-7379-1-git-send-email-Matthieu.Moy@imag.fr>
The behavior of command-line options with optional arguments 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>
---
Documentation/git-am.txt | 3 ++-
Documentation/git-cherry-pick.txt | 3 ++-
Documentation/git-commit-tree.txt | 3 ++-
Documentation/git-commit.txt | 3 ++-
Documentation/git-grep.txt | 4 +++-
Documentation/git-merge.txt | 4 +++-
Documentation/git-rebase.txt | 3 ++-
Documentation/git-revert.txt | 3 ++-
Documentation/git-status.txt | 5 +++--
9 files changed, 21 insertions(+), 10 deletions(-)
diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt
index dbea6e7..5f0082e 100644
--- a/Documentation/git-am.txt
+++ b/Documentation/git-am.txt
@@ -141,7 +141,8 @@ 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; 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 83b3cc2..383f57d 100644
--- a/Documentation/git-cherry-pick.txt
+++ b/Documentation/git-cherry-pick.txt
@@ -103,7 +103,8 @@ effect to your index in a row.
-S[<keyid>]::
--gpg-sign[=<keyid>]::
- GPG-sign commits.
+ GPG-sign commits. The `keyid` argument is optional; 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 f5f2a8d..da2f359 100644
--- a/Documentation/git-commit-tree.txt
+++ b/Documentation/git-commit-tree.txt
@@ -56,7 +56,8 @@ OPTIONS
-S[<keyid>]::
--gpg-sign[=<keyid>]::
- GPG-sign commit.
+ GPG-sign commits. The `keyid` argument is optional; 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 904dafa..99fab5f 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -314,7 +314,8 @@ changes to tracked files.
-S[<keyid>]::
--gpg-sign[=<keyid>]::
- GPG-sign commit.
+ GPG-sign commits. The `keyid` argument is optional; 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 1c07c7f..563d011 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -165,7 +165,9 @@ OPTIONS
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.
-z::
--null::
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index a62d672..8543d88 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -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; 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 ca03954..1894431 100644
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -294,7 +294,8 @@ which makes little sense.
-S[<keyid>]::
--gpg-sign[=<keyid>]::
- GPG-sign commits.
+ GPG-sign commits. The `keyid` argument is optional; 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 6388089..cdc3588 100644
--- a/Documentation/git-revert.txt
+++ b/Documentation/git-revert.txt
@@ -82,7 +82,8 @@ effect to your index in a row.
-S[<keyid>]::
--gpg-sign[=<keyid>]::
- GPG-sign commits.
+ GPG-sign commits. The `keyid` argument is optional; 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 335f312..e1e8f57 100644
--- 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:
+
--
2.5.0.402.g8854c44
next prev parent reply other threads:[~2015-09-18 15:12 UTC|newest]
Thread overview: 16+ messages / expand[flat|nested] mbox.gz Atom feed top
2015-09-17 9:44 git status -u is mildly astonishing Alastair McGowan-Douglas
2015-09-17 14:27 ` Matthieu Moy
2015-09-17 17:43 ` Jeff King
2015-09-18 6:52 ` Matthieu Moy
2015-09-18 15:01 ` [PATCH 0/3] Clarify the documentation of options with optional arguments Matthieu Moy
2015-09-18 15:01 ` [PATCH 1/3] Documentation: use 'keyid' consistantly, not 'key-id' Matthieu Moy
2015-09-18 15:24 ` Matthieu Moy
2015-09-18 19:23 ` Jeff King
2015-09-18 15:01 ` [PATCH 2/3] Documentation/grep: fix documentation of -O Matthieu Moy
2015-09-18 15:01 ` Matthieu Moy [this message]
2015-09-18 19:27 ` [PATCH 3/3] Documentation: make explicit that optional arguments must be stuck Jeff King
2015-09-19 7:47 ` [PATCH v2 0/3] Clarify the documentation of options with optional arguments Matthieu Moy
2015-09-19 7:47 ` [PATCH v2 1/3] Documentation: use 'keyid' consistently, not 'key-id' Matthieu Moy
2015-09-19 7:47 ` [PATCH v2 2/3] Documentation/grep: fix documentation of -O Matthieu Moy
2015-09-19 7:47 ` [PATCH v2 3/3] Documentation: explain optional arguments better Matthieu Moy
2015-09-19 10:50 ` [PATCH v2 0/3] Clarify the documentation of options with optional arguments Jeff King
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1442588510-7379-4-git-send-email-Matthieu.Moy@imag.fr \
--to=matthieu.moy@imag.fr \
--cc=altreus@altre.us \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=peff@peff.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).