{"thread":{"id":"40369","subject":"git status -u is mildly astonishing","startedAt":"2015-09-17T09:44:30Z","lastAt":"2015-09-19T10:50:43Z","messageCount":16,"participants":["Alastair McGowan-Douglas","Matthieu Moy","Jeff King"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"270201","messageId":"20150917104430.5dd73ae1@dev-05","threadId":"40369","inReplyTo":null,"subject":"git status -u is mildly astonishing","fromName":"Alastair McGowan-Douglas","fromEmail":"altreus@altre.us","sentAt":"2015-09-17T09:44:30Z","receivedAt":"2015-09-17T09:44:30Z","isPatch":false,"sender":{"key":"altreus@altre.us","avatar":null},"body":"Hi list,\n\nToday I found what I thought was a bug in git status:\n\nhttps://paste.fedoraproject.org/268333/42480833/\n\nIt seemed that the argument to -u was being ignored. It turns out that\n'no' was not actually being considered an argument to -u in the first\nplace.\n\nThe documentation supports this:\n\n -u[], --untracked-files[=]\n Show untracked files.\n\nThere is no space here, but it is not obvious that it is *important*\nthat there is no space here.\n\nThe usage string implies that -- is used to disambiguate path specs\nfrom option arguments\n\n git status [...] [--] [...]\n\nTherefore I would argue that -u is behaving differently from other\narguments (especially when considered across all git subcommands) by\nonly accepting its argument when not separated by a space. This at\nleast should be explicitly documented, but, preferably, should be\nconsistent with other arguments and use the -- token as the separator.\n\n-Altreus\n"},{"id":"270213","messageId":"vpqd1xhqfxg.fsf@anie.imag.fr","threadId":"40369","inReplyTo":"20150917104430.5dd73ae1@dev-05","subject":"Re: git status -u is mildly astonishing","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2015-09-17T14:27:39Z","receivedAt":"2015-09-17T14:27:39Z","isPatch":false,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Alastair McGowan-Douglas writes:\n\n> It seemed that the argument to -u was being ignored. It turns out that\n> 'no' was not actually being considered an argument to -u in the first\n> place.\n\n-u takes an optional argument. We can't consider the command-line\nargument following u as its argument, because that would mean\n\n git status -u --null\n\nwould be read as\n\n git status -u=--null\n\n> The usage string implies that -- is used to disambiguate path specs\n> from option arguments\n\nYes, but the problem here is not path specs Vs options, but anything Vs\nargument of the previous option.\n\n> Therefore I would argue that -u is behaving differently from other\n> arguments (especially when considered across all git subcommands)\n\nThis is because you have options with non-optional argument in mind, or\noptions that have no short version.\n\nIf I grep the source correctly, the only options accepting a short\nversion and an optional string argument are \"{merge,am,commit,revert}\n-S\", \"grep -O\" and \"status -u\", which behave consistantly.\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"270246","messageId":"20150917174306.GA29171@sigill.intra.peff.net","threadId":"40369","inReplyTo":"vpqd1xhqfxg.fsf@anie.imag.fr","subject":"Re: git status -u is mildly astonishing","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2015-09-17T17:43:07Z","receivedAt":"2015-09-17T17:43:07Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, Sep 17, 2015 at 04:27:39PM +0200, Matthieu Moy wrote:\n\n> > Therefore I would argue that -u is behaving differently from other\n> > arguments (especially when considered across all git subcommands)\n> \n> This is because you have options with non-optional argument in mind, or\n> options that have no short version.\n> \n> If I grep the source correctly, the only options accepting a short\n> version and an optional string argument are \"{merge,am,commit,revert}\n> -S\", \"grep -O\" and \"status -u\", which behave consistantly.\n\nExactly. This is covered in gitcli(7)*, but I wonder if it is worth\ncalling attention to this behavior specifically in the documentation of\nthose options.\n\n-Peff\n\n[*] Try \"git help cli\", the bit starting with 'Here are the rules\n regarding the \"flags\"...'.\n"},{"id":"270275","messageId":"vpq6138md7u.fsf@anie.imag.fr","threadId":"40369","inReplyTo":"20150917174306.GA29171@sigill.intra.peff.net","subject":"Re: git status -u is mildly astonishing","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2015-09-18T06:52:05Z","receivedAt":"2015-09-18T06:52:05Z","isPatch":false,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Jeff King writes:\n\n> On Thu, Sep 17, 2015 at 04:27:39PM +0200, Matthieu Moy wrote:\n>\n>> > Therefore I would argue that -u is behaving differently from other\n>> > arguments (especially when considered across all git subcommands)\n>> \n>> This is because you have options with non-optional argument in mind, or\n>> options that have no short version.\n>> \n>> If I grep the source correctly, the only options accepting a short\n>> version and an optional string argument are \"{merge,am,commit,revert}\n>> -S\", \"grep -O\" and \"status -u\", which behave consistantly.\n>\n> Exactly. This is covered in gitcli(7)*, but I wonder if it is worth\n> calling attention to this behavior specifically in the documentation of\n> those options.\n\nI think it does make sense to say it explicitly in the doc for each\noption. There are not many, and even though I think Git is doing the\nright thing, I also have to admit that it's confusing.\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"270295","messageId":"1442588510-7379-1-git-send-email-Matthieu.Moy@imag.fr","threadId":"40369","inReplyTo":"20150917174306.GA29171@sigill.intra.peff.net","subject":"[PATCH 0/3] Clarify the documentation of options with optional arguments","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2015-09-18T15:01:47Z","receivedAt":"2015-09-18T15:01:47Z","isPatch":true,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"The first patch is essentially to make the last one look good. The\nsecond is a real documentation bug. The last one may be controversial\nas it re-documents something already documented in gitcli, but I think\nit's a good thing.\n\nMatthieu Moy (3):\n Documentation: use 'keyid' consistantly, not 'key-id'\n Documentation/grep: fix documentation of -O\n Documentation: make explicit that optional arguments must be stuck\n\n Documentation/git-am.txt | 3 ++-\n Documentation/git-cherry-pick.txt | 7 ++++---\n Documentation/git-commit-tree.txt | 3 ++-\n Documentation/git-commit.txt | 3 ++-\n Documentation/git-grep.txt | 8 +++++---\n Documentation/git-merge.txt | 4 +++-\n Documentation/git-rebase.txt | 3 ++-\n Documentation/git-revert.txt | 7 ++++---\n Documentation/git-status.txt | 5 +++--\n 9 files changed, 27 insertions(+), 16 deletions(-)\n\n-- \n2.5.0.402.g8854c44\n"},{"id":"270296","messageId":"1442588510-7379-2-git-send-email-Matthieu.Moy@imag.fr","threadId":"40369","inReplyTo":"1442588510-7379-1-git-send-email-Matthieu.Moy@imag.fr","subject":"[PATCH 1/3] Documentation: use 'keyid' consistantly, not 'key-id'","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2015-09-18T15:01:48Z","receivedAt":"2015-09-18T15:01:48Z","isPatch":true,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"Signed-off-by: Matthieu Moy \n---\n Documentation/git-cherry-pick.txt | 4 ++--\n Documentation/git-revert.txt | 4 ++--\n 2 files changed, 4 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt\nindex 1147c71..83b3cc2 100644\n--- a/Documentation/git-cherry-pick.txt\n+++ b/Documentation/git-cherry-pick.txt\n@@ -101,8 +101,8 @@ effect to your index in a row.\n --signoff::\n \tAdd Signed-off-by line at the end of the commit message.\n \n--S[]::\n---gpg-sign[=]::\n+-S[]::\n+--gpg-sign[=]::\n \tGPG-sign commits.\n \n --ff::\ndiff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt\nindex cceb5f2..6388089 100644\n--- a/Documentation/git-revert.txt\n+++ b/Documentation/git-revert.txt\n@@ -80,8 +80,8 @@ more details.\n This is useful when reverting more than one commits'\n effect to your index in a row.\n \n--S[]::\n---gpg-sign[=]::\n+-S[]::\n+--gpg-sign[=]::\n \tGPG-sign commits.\n \n -s::\n-- \n2.5.0.402.g8854c44\n"},{"id":"270292","messageId":"1442588510-7379-3-git-send-email-Matthieu.Moy@imag.fr","threadId":"40369","inReplyTo":"1442588510-7379-1-git-send-email-Matthieu.Moy@imag.fr","subject":"[PATCH 2/3] Documentation/grep: fix documentation of -O","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2015-09-18T15:01:49Z","receivedAt":"2015-09-18T15:01:49Z","isPatch":true,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"Since the argument of -O, --open-file-in-pager is optional, it must be\nstuck to the command. Reflect this in the documentation.\n\nSigned-off-by: Matthieu Moy \n---\n Documentation/git-grep.txt | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt\nindex 31811f1..1c07c7f 100644\n--- a/Documentation/git-grep.txt\n+++ b/Documentation/git-grep.txt\n@@ -160,8 +160,8 @@ OPTIONS\n \tFor better compatibility with 'git diff', `--name-only` is a\n \tsynonym for `--files-with-matches`.\n \n--O []::\n---open-files-in-pager []::\n+-O[]::\n+--open-files-in-pager[=]::\n \tOpen the matching files in the pager (not the output of 'grep').\n \tIf the pager happens to be \"less\" or \"vi\", and the user\n \tspecified only one pattern, the first file is positioned at\n-- \n2.5.0.402.g8854c44\n"},{"id":"270294","messageId":"1442588510-7379-4-git-send-email-Matthieu.Moy@imag.fr","threadId":"40369","inReplyTo":"1442588510-7379-1-git-send-email-Matthieu.Moy@imag.fr","subject":"[PATCH 3/3] Documentation: make explicit that optional arguments must be stuck","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2015-09-18T15:01:50Z","receivedAt":"2015-09-18T15:01:50Z","isPatch":true,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"The behavior of command-line options with optional arguments is\ndocumented in gitcli(7), but it is easy for users to miss, and hard for\nthe same user to understand why e.g. \"git status -u no\" does not work.\n\nDocument this explicitly in the documentation of each short option having\nan optional argument: they are the most error prone since there is no '='\nsign between the option and its argument.\n\nSigned-off-by: Matthieu Moy \n---\n Documentation/git-am.txt | 3 ++-\n Documentation/git-cherry-pick.txt | 3 ++-\n Documentation/git-commit-tree.txt | 3 ++-\n Documentation/git-commit.txt | 3 ++-\n Documentation/git-grep.txt | 4 +++-\n Documentation/git-merge.txt | 4 +++-\n Documentation/git-rebase.txt | 3 ++-\n Documentation/git-revert.txt | 3 ++-\n Documentation/git-status.txt | 5 +++--\n 9 files changed, 21 insertions(+), 10 deletions(-)\n\ndiff --git a/Documentation/git-am.txt b/Documentation/git-am.txt\nindex dbea6e7..5f0082e 100644\n--- a/Documentation/git-am.txt\n+++ b/Documentation/git-am.txt\n@@ -141,7 +141,8 @@ default. You can use `--no-utf8` to override this.\n \n -S[]::\n --gpg-sign[=]::\n-\tGPG-sign commits.\n+\tGPG-sign commits. The `keyid` argument is optional; if\n+\tspecified, it must be stuck to the option without a space.\n \n --continue::\n -r::\ndiff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt\nindex 83b3cc2..383f57d 100644\n--- a/Documentation/git-cherry-pick.txt\n+++ b/Documentation/git-cherry-pick.txt\n@@ -103,7 +103,8 @@ effect to your index in a row.\n \n -S[]::\n --gpg-sign[=]::\n-\tGPG-sign commits.\n+\tGPG-sign commits. The `keyid` argument is optional; if\n+\tspecified, it must be stuck to the option without a space.\n \n --ff::\n \tIf the current HEAD is the same as the parent of the\ndiff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt\nindex f5f2a8d..da2f359 100644\n--- a/Documentation/git-commit-tree.txt\n+++ b/Documentation/git-commit-tree.txt\n@@ -56,7 +56,8 @@ OPTIONS\n \n -S[]::\n --gpg-sign[=]::\n-\tGPG-sign commit.\n+\tGPG-sign commits. The `keyid` argument is optional; if\n+\tspecified, it must be stuck to the option without a space.\n \n --no-gpg-sign::\n \tCountermand `commit.gpgSign` configuration variable that is\ndiff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\nindex 904dafa..99fab5f 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -314,7 +314,8 @@ changes to tracked files.\n \n -S[]::\n --gpg-sign[=]::\n-\tGPG-sign commit.\n+\tGPG-sign commits. The `keyid` argument is optional; if\n+\tspecified, it must be stuck to the option without a space.\n \n --no-gpg-sign::\n \tCountermand `commit.gpgSign` configuration variable that is\ndiff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt\nindex 1c07c7f..563d011 100644\n--- a/Documentation/git-grep.txt\n+++ b/Documentation/git-grep.txt\n@@ -165,7 +165,9 @@ OPTIONS\n \tOpen the matching files in the pager (not the output of 'grep').\n \tIf the pager happens to be \"less\" or \"vi\", and the user\n \tspecified only one pattern, the first file is positioned at\n-\tthe first match automatically.\n+\tthe first match automatically. The `pager` argument is\n+\toptional; if specified, it must be stuck to the option\n+\twithout a space.\n \n -z::\n --null::\ndiff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\nindex a62d672..8543d88 100644\n--- a/Documentation/git-merge.txt\n+++ b/Documentation/git-merge.txt\n@@ -67,7 +67,9 @@ include::merge-options.txt[]\n \n -S[]::\n --gpg-sign[=]::\n-\tGPG-sign the resulting merge commit.\n+\tGPG-sign the resulting merge commit. The `keyid` argument is\n+\toptional; if specified, it must be stuck to the option\n+\twithout a space.\n \n -m ::\n \tSet the commit message to be used for the merge commit (in\ndiff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt\nindex ca03954..1894431 100644\n--- a/Documentation/git-rebase.txt\n+++ b/Documentation/git-rebase.txt\n@@ -294,7 +294,8 @@ which makes little sense.\n \n -S[]::\n --gpg-sign[=]::\n-\tGPG-sign commits.\n+\tGPG-sign commits. The `keyid` argument is optional; if\n+\tspecified, it must be stuck to the option without a space.\n \n -q::\n --quiet::\ndiff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt\nindex 6388089..cdc3588 100644\n--- a/Documentation/git-revert.txt\n+++ b/Documentation/git-revert.txt\n@@ -82,7 +82,8 @@ effect to your index in a row.\n \n -S[]::\n --gpg-sign[=]::\n-\tGPG-sign commits.\n+\tGPG-sign commits. The `keyid` argument is optional; if\n+\tspecified, it must be stuck to the option without a space.\n \n -s::\n --signoff::\ndiff --git a/Documentation/git-status.txt b/Documentation/git-status.txt\nindex 335f312..e1e8f57 100644\n--- a/Documentation/git-status.txt\n+++ b/Documentation/git-status.txt\n@@ -53,8 +53,9 @@ OPTIONS\n --untracked-files[=]::\n \tShow untracked files.\n +\n-The mode parameter is optional (defaults to 'all'), and is used to\n-specify the handling of untracked files.\n+The mode parameter is used to specify the handling of untracked files.\n+It is optional: it defaults to 'all', and if specified, it must be\n+stuck to the option (e.g. `-uno`, but not `-u no`).\n +\n The possible options are:\n +\n-- \n2.5.0.402.g8854c44\n"},{"id":"270299","messageId":"vpqvbb7iwcg.fsf@anie.imag.fr","threadId":"40369","inReplyTo":"1442588510-7379-2-git-send-email-Matthieu.Moy@imag.fr","subject":"Re: [PATCH 1/3] Documentation: use 'keyid' consistantly, not 'key-id'","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2015-09-18T15:24:47Z","receivedAt":"2015-09-18T15:24:47Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Subject: ... use 'keyid' consistantly\n\nSorry, should s/consistantly/consistently/. Will resend.\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"270314","messageId":"20150918192345.GD11068@sigill.intra.peff.net","threadId":"40369","inReplyTo":"1442588510-7379-2-git-send-email-Matthieu.Moy@imag.fr","subject":"Re: [PATCH 1/3] Documentation: use 'keyid' consistantly, not 'key-id'","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2015-09-18T19:23:45Z","receivedAt":"2015-09-18T19:23:45Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Fri, Sep 18, 2015 at 05:01:48PM +0200, Matthieu Moy wrote:\n\n> Signed-off-by: Matthieu Moy \n> ---\n> Documentation/git-cherry-pick.txt | 4 ++--\n> Documentation/git-revert.txt | 4 ++--\n> 2 files changed, 4 insertions(+), 4 deletions(-)\n\nHmm, grepping for `key-id` turns up quite a few more hits. Is there any\nreason not to change those, too?\n\n-Peff\n"},{"id":"270316","messageId":"20150918192718.GE11068@sigill.intra.peff.net","threadId":"40369","inReplyTo":"1442588510-7379-4-git-send-email-Matthieu.Moy@imag.fr","subject":"Re: [PATCH 3/3] Documentation: make explicit that optional arguments must be stuck","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2015-09-18T19:27:18Z","receivedAt":"2015-09-18T19:27:18Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Fri, Sep 18, 2015 at 05:01:50PM +0200, Matthieu Moy wrote:\n\n> The behavior of command-line options with optional arguments is\n> documented in gitcli(7), but it is easy for users to miss, and hard for\n> the same user to understand why e.g. \"git status -u no\" does not work.\n> \n> Document this explicitly in the documentation of each short option having\n> an optional argument: they are the most error prone since there is no '='\n> sign between the option and its argument.\n\nI like this. Even though it is redundant, it is getting information to\nthe place where users can see it, and I don't think it is so large as to\nobscure the rest of the content.\n\n> diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt\n> index dbea6e7..5f0082e 100644\n> --- a/Documentation/git-am.txt\n> +++ b/Documentation/git-am.txt\n> @@ -141,7 +141,8 @@ default. You can use `--no-utf8` to override this.\n> \n> -S[]::\n> --gpg-sign[=]::\n> -\tGPG-sign commits.\n> +\tGPG-sign commits. The `keyid` argument is optional; if\n> +\tspecified, it must be stuck to the option without a space.\n\nI think this wording is probably OK. At first I thought it was saying\nthe wrong thing for the long form (\"stuck without a space\" would mean\n\"--gpg-sign[keyid]\"), but I think the syntax just above makes it pretty\nclear.\n\n> diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt\n> index 335f312..e1e8f57 100644\n> --- a/Documentation/git-status.txt\n> +++ b/Documentation/git-status.txt\n> @@ -53,8 +53,9 @@ OPTIONS\n> --untracked-files[=]::\n> \tShow untracked files.\n> +\n> -The mode parameter is optional (defaults to 'all'), and is used to\n> -specify the handling of untracked files.\n> +The mode parameter is used to specify the handling of untracked files.\n> +It is optional: it defaults to 'all', and if specified, it must be\n> +stuck to the option (e.g. `-uno`, but not `-u no`).\n\nI think this rearrangement makes the meaning much more clear overall.\n\n-Peff\n"},{"id":"270331","messageId":"1442648870-22511-1-git-send-email-Matthieu.Moy@imag.fr","threadId":"40369","inReplyTo":"1442588510-7379-1-git-send-email-Matthieu.Moy@imag.fr","subject":"[PATCH v2 0/3] Clarify the documentation of options with optional arguments","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2015-09-19T07:47:47Z","receivedAt":"2015-09-19T07:47:47Z","isPatch":true,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"Changes since v2:\n\n* Typo in commit message\n\n* key-id -> keyid in more places. Not so important, but we had cases\n where SYNOPSYS was saying key-id and the full doc keyid, let's make\n it more uniform (and more grep-able).\n\n* Document what --sign-commit and --open-in-pager do when the optional\n argument is not specified.\n\nMatthieu Moy (3):\n Documentation: use 'keyid' consistently, not 'key-id'\n Documentation/grep: fix documentation of -O\n Documentation: explain optional arguments better\n\n Documentation/git-am.txt | 4 +++-\n Documentation/git-cherry-pick.txt | 10 ++++++----\n Documentation/git-commit-tree.txt | 4 +++-\n Documentation/git-commit.txt | 6 ++++--\n Documentation/git-grep.txt | 9 ++++++---\n Documentation/git-merge.txt | 6 ++++--\n Documentation/git-rebase.txt | 4 +++-\n Documentation/git-revert.txt | 10 ++++++----\n Documentation/git-status.txt | 5 +++--\n Documentation/git-tag.txt | 18 +++++++++---------\n 10 files changed, 47 insertions(+), 29 deletions(-)\n\n-- \n2.5.0.402.g8854c44\n"},{"id":"270329","messageId":"1442648870-22511-2-git-send-email-Matthieu.Moy@imag.fr","threadId":"40369","inReplyTo":"1442648870-22511-1-git-send-email-Matthieu.Moy@imag.fr","subject":"[PATCH v2 1/3] Documentation: use 'keyid' consistently, not 'key-id'","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2015-09-19T07:47:48Z","receivedAt":"2015-09-19T07:47:48Z","isPatch":true,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"Signed-off-by: Matthieu Moy \n---\n Documentation/git-cherry-pick.txt | 6 +++---\n Documentation/git-commit.txt | 2 +-\n Documentation/git-merge.txt | 2 +-\n Documentation/git-revert.txt | 6 +++---\n Documentation/git-tag.txt | 18 +++++++++---------\n 5 files changed, 17 insertions(+), 17 deletions(-)\n\ndiff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt\nindex 1147c71..66ab297 100644\n--- a/Documentation/git-cherry-pick.txt\n+++ b/Documentation/git-cherry-pick.txt\n@@ -9,7 +9,7 @@ SYNOPSIS\n --------\n [verse]\n 'git cherry-pick' [--edit] [-n] [-m parent-number] [-s] [-x] [--ff]\n-\t\t [-S[]] ...\n+\t\t [-S[]] ...\n 'git cherry-pick' --continue\n 'git cherry-pick' --quit\n 'git cherry-pick' --abort\n@@ -101,8 +101,8 @@ effect to your index in a row.\n --signoff::\n \tAdd Signed-off-by line at the end of the commit message.\n \n--S[]::\n---gpg-sign[=]::\n+-S[]::\n+--gpg-sign[=]::\n \tGPG-sign commits.\n \n --ff::\ndiff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\nindex 904dafa..51c63d6 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -13,7 +13,7 @@ SYNOPSIS\n \t [-F | -m ] [--reset-author] [--allow-empty]\n \t [--allow-empty-message] [--no-verify] [-e] [--author=]\n \t [--date=] [--cleanup=] [--[no-]status]\n-\t [-i | -o] [-S[]] [--] [...]\n+\t [-i | -o] [-S[]] [--] [...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\nindex a62d672..98bf7b1 100644\n--- a/Documentation/git-merge.txt\n+++ b/Documentation/git-merge.txt\n@@ -10,7 +10,7 @@ SYNOPSIS\n --------\n [verse]\n 'git merge' [-n] [--stat] [--no-commit] [--squash] [--[no-]edit]\n-\t[-s ] [-X ] [-S[]]\n+\t[-s ] [-X ] [-S[]]\n \t[--[no-]rerere-autoupdate] [-m ] [...]\n 'git merge' HEAD ...\n 'git merge' --abort\ndiff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt\nindex cceb5f2..9eb83f0 100644\n--- a/Documentation/git-revert.txt\n+++ b/Documentation/git-revert.txt\n@@ -8,7 +8,7 @@ git-revert - Revert some existing commits\n SYNOPSIS\n --------\n [verse]\n-'git revert' [--[no-]edit] [-n] [-m parent-number] [-s] [-S[]] ...\n+'git revert' [--[no-]edit] [-n] [-m parent-number] [-s] [-S[]] ...\n 'git revert' --continue\n 'git revert' --quit\n 'git revert' --abort\n@@ -80,8 +80,8 @@ more details.\n This is useful when reverting more than one commits'\n effect to your index in a row.\n \n--S[]::\n---gpg-sign[=]::\n+-S[]::\n+--gpg-sign[=]::\n \tGPG-sign commits.\n \n -s::\ndiff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt\nindex 84f6496..08b4dfb 100644\n--- a/Documentation/git-tag.txt\n+++ b/Documentation/git-tag.txt\n@@ -9,7 +9,7 @@ git-tag - Create, list, delete or verify a tag object signed with GPG\n SYNOPSIS\n --------\n [verse]\n-'git tag' [-a | -s | -u ] [-f] [-m | -F ]\n+'git tag' [-a | -s | -u ] [-f] [-m | -F ]\n \t [ | ]\n 'git tag' -d ...\n 'git tag' [-n[]] -l [--contains ] [--points-at ]\n@@ -24,19 +24,19 @@ to delete, list or verify tags.\n \n Unless `-f` is given, the named tag must not yet exist.\n \n-If one of `-a`, `-s`, or `-u ` is passed, the command\n+If one of `-a`, `-s`, or `-u ` is passed, the command\n creates a 'tag' object, and requires a tag message. Unless\n `-m ` or `-F ` is given, an editor is started for the user to type\n in the tag message.\n \n-If `-m ` or `-F ` is given and `-a`, `-s`, and `-u `\n+If `-m ` or `-F ` is given and `-a`, `-s`, and `-u `\n are absent, `-a` is implied.\n \n Otherwise just a tag reference for the SHA-1 object name of the commit object is\n created (i.e. a lightweight tag).\n \n A GnuPG signed tag object will be created when `-s` or `-u\n-` is used. When `-u ` is not used, the\n+` is used. When `-u ` is not used, the\n committer identity for the current user is used to find the\n GnuPG key for signing. \tThe configuration variable `gpg.program`\n is used to specify custom GnuPG binary.\n@@ -63,8 +63,8 @@ OPTIONS\n --sign::\n \tMake a GPG-signed tag, using the default e-mail address's key.\n \n--u ::\n---local-user=::\n+-u ::\n+--local-user=::\n \tMake a GPG-signed tag, using the given key.\n \n -f::\n@@ -125,14 +125,14 @@ This option is only applicable when listing tags without annotation lines.\n \tUse the given tag message (instead of prompting).\n \tIf multiple `-m` options are given, their values are\n \tconcatenated as separate paragraphs.\n-\tImplies `-a` if none of `-a`, `-s`, or `-u `\n+\tImplies `-a` if none of `-a`, `-s`, or `-u `\n \tis given.\n \n -F ::\n --file=::\n \tTake the tag message from the given file. Use '-' to\n \tread the message from the standard input.\n-\tImplies `-a` if none of `-a`, `-s`, or `-u `\n+\tImplies `-a` if none of `-a`, `-s`, or `-u `\n \tis given.\n \n --cleanup=::\n@@ -166,7 +166,7 @@ it in the repository configuration as follows:\n \n -------------------------------------\n [user]\n- signingKey = \n+ signingKey = \n -------------------------------------\n \n \n-- \n2.5.0.402.g8854c44\n"},{"id":"270332","messageId":"1442648870-22511-3-git-send-email-Matthieu.Moy@imag.fr","threadId":"40369","inReplyTo":"1442648870-22511-1-git-send-email-Matthieu.Moy@imag.fr","subject":"[PATCH v2 2/3] Documentation/grep: fix documentation of -O","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2015-09-19T07:47:49Z","receivedAt":"2015-09-19T07:47:49Z","isPatch":true,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"Since the argument of -O, --open-file-in-pager is optional, it must be\nstuck to the command. Reflect this in the documentation.\n\nSigned-off-by: Matthieu Moy \n---\n Documentation/git-grep.txt | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt\nindex 31811f1..1c07c7f 100644\n--- a/Documentation/git-grep.txt\n+++ b/Documentation/git-grep.txt\n@@ -160,8 +160,8 @@ OPTIONS\n \tFor better compatibility with 'git diff', `--name-only` is a\n \tsynonym for `--files-with-matches`.\n \n--O []::\n---open-files-in-pager []::\n+-O[]::\n+--open-files-in-pager[=]::\n \tOpen the matching files in the pager (not the output of 'grep').\n \tIf the pager happens to be \"less\" or \"vi\", and the user\n \tspecified only one pattern, the first file is positioned at\n-- \n2.5.0.402.g8854c44\n"},{"id":"270330","messageId":"1442648870-22511-4-git-send-email-Matthieu.Moy@imag.fr","threadId":"40369","inReplyTo":"1442648870-22511-1-git-send-email-Matthieu.Moy@imag.fr","subject":"[PATCH v2 3/3] Documentation: explain optional arguments better","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2015-09-19T07:47:50Z","receivedAt":"2015-09-19T07:47:50Z","isPatch":true,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"Improve the documentation of commands taking optional arguments in two\nways:\n\n* Documents the behavior of '-O' (for grep) and '-S' (for commands\n creating commits) when used without the optional argument.\n\n* Document the syntax of these options.\n\nFor the second point, the behavior is documented in gitcli(7), but it is\neasy for users to miss, and hard for the same user to understand why e.g.\n\"git status -u no\" does not work.\n\nDocument this explicitly in the documentation of each short option having\nan optional argument: they are the most error prone since there is no '='\nsign between the option and its argument.\n\nSigned-off-by: Matthieu Moy \n---\n Documentation/git-am.txt | 4 +++-\n Documentation/git-cherry-pick.txt | 4 +++-\n Documentation/git-commit-tree.txt | 4 +++-\n Documentation/git-commit.txt | 4 +++-\n Documentation/git-grep.txt | 5 ++++-\n Documentation/git-merge.txt | 4 +++-\n Documentation/git-rebase.txt | 4 +++-\n Documentation/git-revert.txt | 4 +++-\n Documentation/git-status.txt | 5 +++--\n 9 files changed, 28 insertions(+), 10 deletions(-)\n\ndiff --git a/Documentation/git-am.txt b/Documentation/git-am.txt\nindex dbea6e7..452c1fe 100644\n--- a/Documentation/git-am.txt\n+++ b/Documentation/git-am.txt\n@@ -141,7 +141,9 @@ default. You can use `--no-utf8` to override this.\n \n -S[]::\n --gpg-sign[=]::\n-\tGPG-sign commits.\n+\tGPG-sign commits. The `keyid` argument is optional and\n+\tdefaults to the committer identity; if specified, it must be\n+\tstuck to the option without a space.\n \n --continue::\n -r::\ndiff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt\nindex 66ab297..77da29a 100644\n--- a/Documentation/git-cherry-pick.txt\n+++ b/Documentation/git-cherry-pick.txt\n@@ -103,7 +103,9 @@ effect to your index in a row.\n \n -S[]::\n --gpg-sign[=]::\n-\tGPG-sign commits.\n+\tGPG-sign commits. The `keyid` argument is optional and\n+\tdefaults to the committer identity; if specified, it must be\n+\tstuck to the option without a space.\n \n --ff::\n \tIf the current HEAD is the same as the parent of the\ndiff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt\nindex f5f2a8d..a0b5457 100644\n--- a/Documentation/git-commit-tree.txt\n+++ b/Documentation/git-commit-tree.txt\n@@ -56,7 +56,9 @@ OPTIONS\n \n -S[]::\n --gpg-sign[=]::\n-\tGPG-sign commit.\n+\tGPG-sign commits. The `keyid` argument is optional and\n+\tdefaults to the committer identity; if specified, it must be\n+\tstuck to the option without a space.\n \n --no-gpg-sign::\n \tCountermand `commit.gpgSign` configuration variable that is\ndiff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\nindex 51c63d6..7f34a5b 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -314,7 +314,9 @@ changes to tracked files.\n \n -S[]::\n --gpg-sign[=]::\n-\tGPG-sign commit.\n+\tGPG-sign commits. The `keyid` argument is optional and\n+\tdefaults to the committer identity; if specified, it must be\n+\tstuck to the option without a space.\n \n --no-gpg-sign::\n \tCountermand `commit.gpgSign` configuration variable that is\ndiff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt\nindex 1c07c7f..4a44d6d 100644\n--- a/Documentation/git-grep.txt\n+++ b/Documentation/git-grep.txt\n@@ -165,7 +165,10 @@ OPTIONS\n \tOpen the matching files in the pager (not the output of 'grep').\n \tIf the pager happens to be \"less\" or \"vi\", and the user\n \tspecified only one pattern, the first file is positioned at\n-\tthe first match automatically.\n+\tthe first match automatically. The `pager` argument is\n+\toptional; if specified, it must be stuck to the option\n+\twithout a space. If `pager` is unspecified, the default pager\n+\twill be used (see `core.pager` in linkgit:git-config[1]).\n \n -z::\n --null::\ndiff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\nindex 98bf7b1..07f7295 100644\n--- a/Documentation/git-merge.txt\n+++ b/Documentation/git-merge.txt\n@@ -67,7 +67,9 @@ include::merge-options.txt[]\n \n -S[]::\n --gpg-sign[=]::\n-\tGPG-sign the resulting merge commit.\n+\tGPG-sign the resulting merge commit. The `keyid` argument is\n+\toptional and defaults to the committer identity; if specified,\n+\tit must be stuck to the option without a space.\n \n -m ::\n \tSet the commit message to be used for the merge commit (in\ndiff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt\nindex ca03954..bccfdf7 100644\n--- a/Documentation/git-rebase.txt\n+++ b/Documentation/git-rebase.txt\n@@ -294,7 +294,9 @@ which makes little sense.\n \n -S[]::\n --gpg-sign[=]::\n-\tGPG-sign commits.\n+\tGPG-sign commits. The `keyid` argument is optional and\n+\tdefaults to the committer identity; if specified, it must be\n+\tstuck to the option without a space.\n \n -q::\n --quiet::\ndiff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt\nindex 9eb83f0..b15139f 100644\n--- a/Documentation/git-revert.txt\n+++ b/Documentation/git-revert.txt\n@@ -82,7 +82,9 @@ effect to your index in a row.\n \n -S[]::\n --gpg-sign[=]::\n-\tGPG-sign commits.\n+\tGPG-sign commits. The `keyid` argument is optional and\n+\tdefaults to the committer identity; if specified, it must be\n+\tstuck to the option without a space.\n \n -s::\n --signoff::\ndiff --git a/Documentation/git-status.txt b/Documentation/git-status.txt\nindex 335f312..e1e8f57 100644\n--- a/Documentation/git-status.txt\n+++ b/Documentation/git-status.txt\n@@ -53,8 +53,9 @@ OPTIONS\n --untracked-files[=]::\n \tShow untracked files.\n +\n-The mode parameter is optional (defaults to 'all'), and is used to\n-specify the handling of untracked files.\n+The mode parameter is used to specify the handling of untracked files.\n+It is optional: it defaults to 'all', and if specified, it must be\n+stuck to the option (e.g. `-uno`, but not `-u no`).\n +\n The possible options are:\n +\n-- \n2.5.0.402.g8854c44\n"},{"id":"270334","messageId":"20150919105043.GA23464@sigill.intra.peff.net","threadId":"40369","inReplyTo":"1442648870-22511-1-git-send-email-Matthieu.Moy@imag.fr","subject":"Re: [PATCH v2 0/3] Clarify the documentation of options with optional arguments","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2015-09-19T10:50:43Z","receivedAt":"2015-09-19T10:50:43Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sat, Sep 19, 2015 at 09:47:47AM +0200, Matthieu Moy wrote:\n\n> Changes since v2:\n> \n> * Typo in commit message\n> \n> * key-id -> keyid in more places. Not so important, but we had cases\n> where SYNOPSYS was saying key-id and the full doc keyid, let's make\n> it more uniform (and more grep-able).\n> \n> * Document what --sign-commit and --open-in-pager do when the optional\n> argument is not specified.\n> \n> Matthieu Moy (3):\n> Documentation: use 'keyid' consistently, not 'key-id'\n> Documentation/grep: fix documentation of -O\n> Documentation: explain optional arguments better\n\nThis all looks good to me.\n\n-Peff\n"}]}