threads / discuss / 40369

git status -u is mildly astonishing

Subject: git status -u is mildly astonishing

## tl;dr

16 messages between Sep 17, 2015 and Sep 19, 2015.

replies: 15people: 4as markdown or json

Alastair McGowan-Douglas· Sep 17, 2015, 09:44 UTC · lore

Hi list,

Today I found what I thought was a bug in git status:

https://paste.fedoraproject.org/268333/42480833/

It seemed that the argument to -u was being ignored. It turns out that 'no' was not actually being considered an argument to -u in the first place.

The documentation supports this:

       -u[<mode>], --untracked-files[=<mode>]
           Show untracked files.

There is no space here, but it is not obvious that it is *important* that there is no space here.

The usage string implies that -- is used to disambiguate path specs from option arguments

    git status [<options>...] [--] [<pathspec>...]

Therefore I would argue that -u is behaving differently from other arguments (especially when considered across all git subcommands) by only accepting its argument when not separated by a space. This at least should be explicitly documented, but, preferably, should be consistent with other arguments and use the -- token as the separator.

-Altreus

Matthieu Moy· Sep 17, 2015, 14:27 UTC · re: Alastair McGowan-Douglas · lore

Re: git status -u is mildly astonishing

Alastair McGowan-Douglas <altreus@altre.us> writes:

> It seemed that the argument to -u was being ignored. It turns out that
> 'no' was not actually being considered an argument to -u in the first
> place.

-u takes an optional argument. We can't consider the command-line argument following u as its argument, because that would mean

  git status -u --null

would be read as

  git status -u=--null

> The usage string implies that -- is used to disambiguate path specs
> from option arguments

Yes, but the problem here is not path specs Vs options, but anything Vs argument of the previous option.

> Therefore I would argue that -u is behaving differently from other
> arguments (especially when considered across all git subcommands)

This is because you have options with non-optional argument in mind, or options that have no short version.

If I grep the source correctly, the only options accepting a short version and an optional string argument are "{merge,am,commit,revert} -S", "grep -O" and "status -u", which behave consistantly.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Jeff King· Sep 17, 2015, 17:43 UTC · re: Matthieu Moy · lore

Re: git status -u is mildly astonishing

On Thu, Sep 17, 2015 at 04:27:39PM +0200, Matthieu Moy wrote:

Show 9 quoted lines

> > Therefore I would argue that -u is behaving differently from other
> > arguments (especially when considered across all git subcommands)
> 
> This is because you have options with non-optional argument in mind, or
> options that have no short version.
> 
> If I grep the source correctly, the only options accepting a short
> version and an optional string argument are "{merge,am,commit,revert}
> -S", "grep -O" and "status -u", which behave consistantly.

Exactly. This is covered in gitcli(7)*, but I wonder if it is worth calling attention to this behavior specifically in the documentation of those options.

-Peff

[*] Try "git help cli", the bit starting with 'Here are the rules
    regarding the "flags"...'.

Matthieu Moy· Sep 18, 2015, 06:52 UTC · re: Jeff King · lore

Re: git status -u is mildly astonishing

Jeff King <peff@peff.net> writes:

Show 15 quoted lines

> On Thu, Sep 17, 2015 at 04:27:39PM +0200, Matthieu Moy wrote:
>
>> > Therefore I would argue that -u is behaving differently from other
>> > arguments (especially when considered across all git subcommands)
>> 
>> This is because you have options with non-optional argument in mind, or
>> options that have no short version.
>> 
>> If I grep the source correctly, the only options accepting a short
>> version and an optional string argument are "{merge,am,commit,revert}
>> -S", "grep -O" and "status -u", which behave consistantly.
>
> Exactly. This is covered in gitcli(7)*, but I wonder if it is worth
> calling attention to this behavior specifically in the documentation of
> those options.

I think it does make sense to say it explicitly in the doc for each option. There are not many, and even though I think Git is doing the right thing, I also have to admit that it's confusing.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Matthieu Moy· Sep 18, 2015, 15:01 UTC · re: Jeff King · lore

[PATCH 0/3] Clarify the documentation of options with optional arguments

The first patch is essentially to make the last one look good. The second is a real documentation bug. The last one may be controversial as it re-documents something already documented in gitcli, but I think it's a good thing.

Matthieu Moy (3):
  Documentation: use 'keyid' consistantly, not 'key-id'
  Documentation/grep: fix documentation of -O
  Documentation: make explicit that optional arguments must be stuck

 Documentation/git-am.txt          | 3 ++-
 Documentation/git-cherry-pick.txt | 7 ++++---
 Documentation/git-commit-tree.txt | 3 ++-
 Documentation/git-commit.txt      | 3 ++-
 Documentation/git-grep.txt        | 8 +++++---
 Documentation/git-merge.txt       | 4 +++-
 Documentation/git-rebase.txt      | 3 ++-
 Documentation/git-revert.txt      | 7 ++++---
 Documentation/git-status.txt      | 5 +++--
 9 files changed, 27 insertions(+), 16 deletions(-)

-- 
2.5.0.402.g8854c44

Matthieu Moy· Sep 18, 2015, 15:01 UTC · re: Matthieu Moy · lore

[PATCH 1/3] Documentation: use 'keyid' consistantly, not 'key-id'

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
 Documentation/git-cherry-pick.txt | 4 ++--
 Documentation/git-revert.txt      | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt
index 1147c71..83b3cc2 100644
--- a/Documentation/git-cherry-pick.txt
+++ b/Documentation/git-cherry-pick.txt
@@ -101,8 +101,8 @@ 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>]::
+-S[<keyid>]::
+--gpg-sign[=<keyid>]::
 	GPG-sign commits.
 
 --ff::
diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt
index cceb5f2..6388089 100644
--- a/Documentation/git-revert.txt
+++ b/Documentation/git-revert.txt
@@ -80,8 +80,8 @@ 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>]::
+-S[<keyid>]::
+--gpg-sign[=<keyid>]::
 	GPG-sign commits.
 
 -s::

-- 
2.5.0.402.g8854c44

Matthieu Moy· Sep 18, 2015, 15:24 UTC · re: Matthieu Moy · lore

Re: [PATCH 1/3] Documentation: use 'keyid' consistantly, not 'key-id'

Subject: ... use 'keyid' consistantly

Sorry, should s/consistantly/consistently/. Will resend.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Jeff King· Sep 18, 2015, 19:23 UTC · re: Matthieu Moy · lore

Re: [PATCH 1/3] Documentation: use 'keyid' consistantly, not 'key-id'

On Fri, Sep 18, 2015 at 05:01:48PM +0200, Matthieu Moy wrote:

Show 5 quoted lines

> Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
> ---
>  Documentation/git-cherry-pick.txt | 4 ++--
>  Documentation/git-revert.txt      | 4 ++--
>  2 files changed, 4 insertions(+), 4 deletions(-)

Hmm, grepping for `key-id` turns up quite a few more hits. Is there any reason not to change those, too?

-Peff

Matthieu Moy· Sep 18, 2015, 15:01 UTC · re: Matthieu Moy · lore

[PATCH 2/3] Documentation/grep: fix documentation of -O

Since the argument of -O, --open-file-in-pager is optional, it must be stuck to the command. Reflect this in the documentation.

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
 Documentation/git-grep.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
index 31811f1..1c07c7f 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -160,8 +160,8 @@ 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

-- 
2.5.0.402.g8854c44

Matthieu Moy· Sep 18, 2015, 15:01 UTC · re: Matthieu Moy · lore

[PATCH 3/3] Documentation: make explicit that optional arguments must be stuck

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

Jeff King· Sep 18, 2015, 19:27 UTC · re: Matthieu Moy · lore

Re: [PATCH 3/3] Documentation: make explicit that optional arguments must be stuck

On Fri, Sep 18, 2015 at 05:01:50PM +0200, Matthieu Moy wrote:

Show 7 quoted lines

> 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.

I like this. Even though it is redundant, it is getting information to the place where users can see it, and I don't think it is so large as to obscure the rest of the content.

Show 11 quoted lines

> 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.

I think this wording is probably OK. At first I thought it was saying the wrong thing for the long form ("stuck without a space" would mean "--gpg-sign[keyid]"), but I think the syntax just above makes it pretty clear.

Show 13 quoted lines

> 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`).

I think this rearrangement makes the meaning much more clear overall.

-Peff

Matthieu Moy· Sep 19, 2015, 07:47 UTC · re: Matthieu Moy · lore

[PATCH v2 0/3] Clarify the documentation of options with optional arguments

Changes since v2:

* Typo in commit message

* key-id -> keyid in more places. Not so important, but we had cases
  where SYNOPSYS was saying key-id and the full doc keyid, let's make
  it more uniform (and more grep-able).

* Document what --sign-commit and --open-in-pager do when the optional
  argument is not specified.

Matthieu Moy (3):
  Documentation: use 'keyid' consistently, not 'key-id'
  Documentation/grep: fix documentation of -O
  Documentation: explain optional arguments better

 Documentation/git-am.txt          |  4 +++-
 Documentation/git-cherry-pick.txt | 10 ++++++----
 Documentation/git-commit-tree.txt |  4 +++-
 Documentation/git-commit.txt      |  6 ++++--
 Documentation/git-grep.txt        |  9 ++++++---
 Documentation/git-merge.txt       |  6 ++++--
 Documentation/git-rebase.txt      |  4 +++-
 Documentation/git-revert.txt      | 10 ++++++----
 Documentation/git-status.txt      |  5 +++--
 Documentation/git-tag.txt         | 18 +++++++++---------
 10 files changed, 47 insertions(+), 29 deletions(-)

-- 
2.5.0.402.g8854c44

Matthieu Moy· Sep 19, 2015, 07:47 UTC · re: Matthieu Moy · lore

[PATCH v2 1/3] Documentation: use 'keyid' consistently, not 'key-id'

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
 Documentation/git-cherry-pick.txt |  6 +++---
 Documentation/git-commit.txt      |  2 +-
 Documentation/git-merge.txt       |  2 +-
 Documentation/git-revert.txt      |  6 +++---
 Documentation/git-tag.txt         | 18 +++++++++---------
 5 files changed, 17 insertions(+), 17 deletions(-)

diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt
index 1147c71..66ab297 100644
--- 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,8 +101,8 @@ 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>]::
+-S[<keyid>]::
+--gpg-sign[=<keyid>]::
 	GPG-sign commits.
 
 --ff::
diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index 904dafa..51c63d6 100644
--- 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
 -----------
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index a62d672..98bf7b1 100644
--- 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
diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt
index cceb5f2..9eb83f0 100644
--- 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,8 +80,8 @@ 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>]::
+-S[<keyid>]::
+--gpg-sign[=<keyid>]::
 	GPG-sign commits.
 
 -s::
diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
index 84f6496..08b4dfb 100644
--- 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>
 -------------------------------------

-- 
2.5.0.402.g8854c44

Matthieu Moy· Sep 19, 2015, 07:47 UTC · re: Matthieu Moy · lore

[PATCH v2 2/3] Documentation/grep: fix documentation of -O

Since the argument of -O, --open-file-in-pager is optional, it must be stuck to the command. Reflect this in the documentation.

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
 Documentation/git-grep.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
index 31811f1..1c07c7f 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -160,8 +160,8 @@ 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

-- 
2.5.0.402.g8854c44

Matthieu Moy· Sep 19, 2015, 07:47 UTC · re: Matthieu Moy · lore

[PATCH v2 3/3] 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>
---
 Documentation/git-am.txt          | 4 +++-
 Documentation/git-cherry-pick.txt | 4 +++-
 Documentation/git-commit-tree.txt | 4 +++-
 Documentation/git-commit.txt      | 4 +++-
 Documentation/git-grep.txt        | 5 ++++-
 Documentation/git-merge.txt       | 4 +++-
 Documentation/git-rebase.txt      | 4 +++-
 Documentation/git-revert.txt      | 4 +++-
 Documentation/git-status.txt      | 5 +++--
 9 files changed, 28 insertions(+), 10 deletions(-)

diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt
index dbea6e7..452c1fe 100644
--- 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 66ab297..77da29a 100644
--- a/Documentation/git-cherry-pick.txt
+++ b/Documentation/git-cherry-pick.txt
@@ -103,7 +103,9 @@ effect to your index in a row.
 
 -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.
 
 --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..a0b5457 100644
--- 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 51c63d6..7f34a5b 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -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 1c07c7f..4a44d6d 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -165,7 +165,10 @@ 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. 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 98bf7b1..07f7295 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 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 ca03954..bccfdf7 100644
--- 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 9eb83f0..b15139f 100644
--- a/Documentation/git-revert.txt
+++ b/Documentation/git-revert.txt
@@ -82,7 +82,9 @@ effect to your index in a row.
 
 -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.
 
 -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

Jeff King· Sep 19, 2015, 10:50 UTC · re: Matthieu Moy · lore

Re: [PATCH v2 0/3] Clarify the documentation of options with optional arguments

On Sat, Sep 19, 2015 at 09:47:47AM +0200, Matthieu Moy wrote:

Show 15 quoted lines

> Changes since v2:
> 
> * Typo in commit message
> 
> * key-id -> keyid in more places. Not so important, but we had cases
>   where SYNOPSYS was saying key-id and the full doc keyid, let's make
>   it more uniform (and more grep-able).
> 
> * Document what --sign-commit and --open-in-pager do when the optional
>   argument is not specified.
> 
> Matthieu Moy (3):
>   Documentation: use 'keyid' consistently, not 'key-id'
>   Documentation/grep: fix documentation of -O
>   Documentation: explain optional arguments better

This all looks good to me.

-Peff