[PATCH 0/7] Cleaning up --help-all inconsistencies

[PATCH 0/7] Cleaning up --help-all inconsistencies

[Michael J Gruber]

While looking at our use of short options, I noticed that several
identical options are described differently in --help-all output of
different commands. This mini series fixes this up. I also smuggled in a
patch to git-tag.txt, whose description section is worded as if "create"
was the only mode (and thus makes incorrect statements about options).

Michael J Gruber (7):
  commit,tag: use same wording for -F
  push: describe --porcelain just like commit and status
  clone,init: describe --template using the same wording
  merge,tag: describe -m just like commit
  add: describe --patch like checkout, reset
  commit,status: describe -u likewise
  git-tag.txt: list all modes in the description

 Documentation/git-tag.txt |    8 +++++++-
 builtin/add.c             |    2 +-
 builtin/clone.c           |    4 ++--
 builtin/commit.c          |    4 ++--
 builtin/init-db.c         |    2 +-
 builtin/merge.c           |    4 ++--
 builtin/push.c            |    2 +-
 builtin/tag.c             |    6 +++---
 8 files changed, 19 insertions(+), 13 deletions(-)

-- 
1.7.4.1.74.gf39475

[PATCH 1/7] commit,tag: use same wording for -F

[Michael J Gruber]

Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
---
 builtin/commit.c |    2 +-
 builtin/tag.c    |    2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/builtin/commit.c b/builtin/commit.c
index 03cff5a..8a534de 100644
--- a/builtin/commit.c
+++ b/builtin/commit.c
@@ -118,7 +118,7 @@ static struct option builtin_commit_options[] = {
 	OPT__VERBOSE(&verbose, "show diff in commit message template"),
 
 	OPT_GROUP("Commit message options"),
-	OPT_FILENAME('F', "file", &logfile, "read log from file"),
+	OPT_FILENAME('F', "file", &logfile, "read message from file"),
 	OPT_STRING(0, "author", &force_author, "AUTHOR", "override author for commit"),
 	OPT_STRING(0, "date", &force_date, "DATE", "override date for commit"),
 	OPT_CALLBACK('m', "message", &message, "MESSAGE", "specify commit message", opt_parse_m),
diff --git a/builtin/tag.c b/builtin/tag.c
index aa1f87d..6408171 100644
--- a/builtin/tag.c
+++ b/builtin/tag.c
@@ -378,7 +378,7 @@ int cmd_tag(int argc, const char **argv, const char *prefix)
 					"annotated tag, needs a message"),
 		OPT_CALLBACK('m', NULL, &msg, "msg",
 			     "message for the tag", parse_msg_arg),
-		OPT_FILENAME('F', NULL, &msgfile, "message in a file"),
+		OPT_FILENAME('F', NULL, &msgfile, "read message from file"),
 		OPT_BOOLEAN('s', NULL, &sign, "annotated and GPG-signed tag"),
 		OPT_STRING('u', NULL, &keyid, "key-id",
 					"use another key to sign the tag"),
-- 
1.7.4.1.74.gf39475

[PATCH 2/7] push: describe --porcelain just like commit and status

[Michael J Gruber]

Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
---
 builtin/push.c |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/builtin/push.c b/builtin/push.c
index e655eb7..e4ff264 100644
--- a/builtin/push.c
+++ b/builtin/push.c
@@ -217,7 +217,7 @@ int cmd_push(int argc, const char **argv, const char *prefix)
 		OPT_BOOLEAN( 0, "delete", &deleterefs, "delete refs"),
 		OPT_BOOLEAN( 0 , "tags", &tags, "push tags (can't be used with --all or --mirror)"),
 		OPT_BIT('n' , "dry-run", &flags, "dry run", TRANSPORT_PUSH_DRY_RUN),
-		OPT_BIT( 0,  "porcelain", &flags, "machine-readable output", TRANSPORT_PUSH_PORCELAIN),
+		OPT_BIT( 0,  "porcelain", &flags, "show porcelain output format", TRANSPORT_PUSH_PORCELAIN),
 		OPT_BIT('f', "force", &flags, "force updates", TRANSPORT_PUSH_FORCE),
 		OPT_BOOLEAN( 0 , "thin", &thin, "use thin pack"),
 		OPT_STRING( 0 , "receive-pack", &receivepack, "receive-pack", "receive pack program"),
-- 
1.7.4.1.74.gf39475

[PATCH 3/7] clone,init: describe --template using the same wording

[Michael J Gruber]

This also corrects a wrong description for clone.

Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
---
 builtin/clone.c   |    4 ++--
 builtin/init-db.c |    2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/builtin/clone.c b/builtin/clone.c
index 82a6938..60d9a64 100644
--- a/builtin/clone.c
+++ b/builtin/clone.c
@@ -68,8 +68,8 @@ static struct option builtin_clone_options[] = {
 		    "initialize submodules in the clone"),
 	OPT_BOOLEAN(0, "recurse-submodules", &option_recursive,
 		    "initialize submodules in the clone"),
-	OPT_STRING(0, "template", &option_template, "path",
-		   "path the template repository"),
+	OPT_STRING(0, "template", &option_template, "template-directory",
+		   "directory from which templates will be used"),
 	OPT_STRING(0, "reference", &option_reference, "repo",
 		   "reference repository"),
 	OPT_STRING('o', "origin", &option_origin, "branch",
diff --git a/builtin/init-db.c b/builtin/init-db.c
index e3af9ea..4f5348e 100644
--- a/builtin/init-db.c
+++ b/builtin/init-db.c
@@ -419,7 +419,7 @@ int cmd_init_db(int argc, const char **argv, const char *prefix)
 	unsigned int flags = 0;
 	const struct option init_db_options[] = {
 		OPT_STRING(0, "template", &template_dir, "template-directory",
-				"provide the directory from which templates will be used"),
+				"directory from which templates will be used"),
 		OPT_SET_INT(0, "bare", &is_bare_repository_cfg,
 				"create a bare repository", 1),
 		{ OPTION_CALLBACK, 0, "shared", &init_shared_repository,
-- 
1.7.4.1.74.gf39475

[PATCH 4/7] merge,tag: describe -m just like commit

[Michael J Gruber]

This also removes the misleading "if any" which sounds as if omitting
"-m" would omit the commmit message. (It meant to mean "if a merge
commit is created at all".)

Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
---
 builtin/merge.c |    4 ++--
 builtin/tag.c   |    4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/builtin/merge.c b/builtin/merge.c
index 9403747..cbbd053 100644
--- a/builtin/merge.c
+++ b/builtin/merge.c
@@ -194,8 +194,8 @@ static struct option builtin_merge_options[] = {
 		"merge strategy to use", option_parse_strategy),
 	OPT_CALLBACK('X', "strategy-option", &xopts, "option=value",
 		"option for selected merge strategy", option_parse_x),
-	OPT_CALLBACK('m', "message", &merge_msg, "message",
-		"message to be used for the merge commit (if any)",
+	OPT_CALLBACK('m', "message", &merge_msg, "MESSAGE",
+		"specify merge commit message",
 		option_parse_message),
 	OPT__VERBOSITY(&verbosity),
 	OPT_BOOLEAN(0, "abort", &abort_current_merge,
diff --git a/builtin/tag.c b/builtin/tag.c
index 6408171..e135717 100644
--- a/builtin/tag.c
+++ b/builtin/tag.c
@@ -376,8 +376,8 @@ int cmd_tag(int argc, const char **argv, const char *prefix)
 		OPT_GROUP("Tag creation options"),
 		OPT_BOOLEAN('a', NULL, &annotate,
 					"annotated tag, needs a message"),
-		OPT_CALLBACK('m', NULL, &msg, "msg",
-			     "message for the tag", parse_msg_arg),
+		OPT_CALLBACK('m', NULL, &msg, "MESSAGE",
+			     "specify tag message", parse_msg_arg),
 		OPT_FILENAME('F', NULL, &msgfile, "read message from file"),
 		OPT_BOOLEAN('s', NULL, &sign, "annotated and GPG-signed tag"),
 		OPT_STRING('u', NULL, &keyid, "key-id",
-- 
1.7.4.1.74.gf39475

[PATCH 5/7] add: describe --patch like checkout, reset

[Michael J Gruber]

Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
---
 builtin/add.c |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/builtin/add.c b/builtin/add.c
index 5f817ad..f8e51f9 100644
--- a/builtin/add.c
+++ b/builtin/add.c
@@ -317,7 +317,7 @@ static struct option builtin_add_options[] = {
 	OPT__VERBOSE(&verbose, "be verbose"),
 	OPT_GROUP(""),
 	OPT_BOOLEAN('i', "interactive", &add_interactive, "interactive picking"),
-	OPT_BOOLEAN('p', "patch", &patch_interactive, "interactive patching"),
+	OPT_BOOLEAN('p', "patch", &patch_interactive, "select hunks interactively"),
 	OPT_BOOLEAN('e', "edit", &edit_interactive, "edit current diff and apply"),
 	OPT__FORCE(&ignored_too, "allow adding otherwise ignored files"),
 	OPT_BOOLEAN('u', "update", &take_worktree_changes, "update tracked files"),
-- 
1.7.4.1.74.gf39475

[PATCH 6/7] commit,status: describe -u likewise

[Michael J Gruber]

They differ by one character only. Being exactly equal should help
translations.

Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
---
 builtin/commit.c |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/builtin/commit.c b/builtin/commit.c
index 8a534de..ef2114b 100644
--- a/builtin/commit.c
+++ b/builtin/commit.c
@@ -150,7 +150,7 @@ static struct option builtin_commit_options[] = {
 		    "terminate entries with NUL"),
 	OPT_BOOLEAN(0, "amend", &amend, "amend previous commit"),
 	OPT_BOOLEAN(0, "no-post-rewrite", &no_post_rewrite, "bypass post-rewrite hook"),
-	{ OPTION_STRING, 'u', "untracked-files", &untracked_files_arg, "mode", "show untracked files, optional modes: all, normal, no (Default: all)", PARSE_OPT_OPTARG, NULL, (intptr_t)"all" },
+	{ OPTION_STRING, 'u', "untracked-files", &untracked_files_arg, "mode", "show untracked files, optional modes: all, normal, no. (Default: all)", PARSE_OPT_OPTARG, NULL, (intptr_t)"all" },
 	/* end commit contents options */
 
 	{ OPTION_BOOLEAN, 0, "allow-empty", &allow_empty, NULL,
-- 
1.7.4.1.74.gf39475

[PATCH 7/7] git-tag.txt: list all modes in the description

[Michael J Gruber]

Currently, the description sounds as if it applied always, but most of
its content is true in "create tag mode" only.

Make this clearer by listing all modes and qualifying the main part.

Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
---
 Documentation/git-tag.txt |    8 +++++++-
 1 files changed, 7 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
index 8b169e3..c503f60 100644
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@ -18,7 +18,7 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-Adds a tag reference in `.git/refs/tags/`.
+Without `-d/-l/-v`: Adds a tag reference in `.git/refs/tags/`.
 
 Unless `-f` is given, the tag must not yet exist in
 `.git/refs/tags/` directory.
@@ -39,6 +39,12 @@ A GnuPG signed tag object will be created when `-s` or `-u
 committer identity for the current user is used to find the
 GnuPG key for signing.
 
+With `-d`: Deletes a tag.
+
+With `-l`: List tags.
+
+With `-v`: Verify tags.
+
 OPTIONS
 -------
 -a::
-- 
1.7.4.1.74.gf39475

Re: [PATCH 2/7] push: describe --porcelain just like commit and status

[Johannes Sixt]

On Montag, 14. Februar 2011, Michael J Gruber wrote:
> -		OPT_BIT( 0,  "porcelain", &flags, "machine-readable output",... 
TRANSPORT_PUSH_PORCELAIN),
> +		OPT_BIT( 0,  "porcelain", &flags, "show porcelain output format",...

IMO, this is a step in the wrong direction. It is not at all clear 
that "--porcelain" means "output _for_ porcelain"; it is much more likely to 
be understood as "output _is_ the porcelain". Your new text even supports 
this latter understanding. The original description "machine-readable output" 
is unambiguous and cannot be misunderstood.

-- Hannes

Re: [PATCH 1/7] commit,tag: use same wording for -F

[Junio C Hamano]

Michael J Gruber <git@drmicha.warpmail.net> writes:

> diff --git a/builtin/commit.c b/builtin/commit.c
> index 03cff5a..8a534de 100644
> --- a/builtin/commit.c
> +++ b/builtin/commit.c
> @@ -118,7 +118,7 @@ static struct option builtin_commit_options[] = {
> ...
> -	OPT_FILENAME('F', "file", &logfile, "read log from file"),
> +	OPT_FILENAME('F', "file", &logfile, "read message from file"),
> diff --git a/builtin/tag.c b/builtin/tag.c
> index aa1f87d..6408171 100644
> --- a/builtin/tag.c
> +++ b/builtin/tag.c
> @@ -378,7 +378,7 @@ int cmd_tag(int argc, const char **argv, const char *prefix)
> ...
> -		OPT_FILENAME('F', NULL, &msgfile, "message in a file"),
> +		OPT_FILENAME('F', NULL, &msgfile, "read message from file"),

Makes sense, thanks.

Re: [PATCH 2/7] push: describe --porcelain just like commit and status

[Junio C Hamano]

Michael J Gruber <git@drmicha.warpmail.net> writes:

> -		OPT_BIT( 0,  "porcelain", &flags, "machine-readable output", TRANSPORT_PUSH_PORCELAIN),
> +		OPT_BIT( 0,  "porcelain", &flags, "show porcelain output format", TRANSPORT_PUSH_PORCELAIN),

Thanks, but I wonder if machine-readable is more descriptive than
"porcelain output format", iow, updating commit/status may be better.

The option was meant to mean "output format for Porcelain script writers
to stay machine readable" but it can be misunderstood as "output format
a Porcelain command would produce with chromes and glitters".

Re: [PATCH 3/7] clone,init: describe --template using the same wording

[Junio C Hamano]

Michael J Gruber <git@drmicha.warpmail.net> writes:

> This also corrects a wrong description for clone.
>
> Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
> diff --git a/builtin/clone.c b/builtin/clone.c
> index 82a6938..60d9a64 100644
> --- a/builtin/clone.c
> +++ b/builtin/clone.c
> @@ -68,8 +68,8 @@ static struct option builtin_clone_options[] = {
> ...
> -	OPT_STRING(0, "template", &option_template, "path",
> -		   "path the template repository"),
> +	OPT_STRING(0, "template", &option_template, "template-directory",
> +		   "directory from which templates will be used"),
> diff --git a/builtin/init-db.c b/builtin/init-db.c
> index e3af9ea..4f5348e 100644
> --- a/builtin/init-db.c
> +++ b/builtin/init-db.c
> @@ -419,7 +419,7 @@ int cmd_init_db(int argc, const char **argv, const char *prefix)
> ...
> -				"provide the directory from which templates will be used"),
> +				"directory from which templates will be used"),

Makes perfect sense; thanks.

Re: [PATCH 6/7] commit,status: describe -u likewise

[Junio C Hamano]

Michael J Gruber <git@drmicha.warpmail.net> writes:

> They differ by one character only. Being exactly equal should help
> translations.
>
> Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
> ---
> diff --git a/builtin/commit.c b/builtin/commit.c
> index 8a534de..ef2114b 100644
> --- a/builtin/commit.c
> +++ b/builtin/commit.c
> @@ -150,7 +150,7 @@ static struct option builtin_commit_options[] = {
> ...
> -	{ OPTION_STRING, 'u', "untracked-files", &untracked_files_arg, "mode", "show untracked files, optional modes: all, normal, no (Default: all)", PARSE_OPT_OPTARG, NULL, (intptr_t)"all" },
> +	{ OPTION_STRING, 'u', "untracked-files", &untracked_files_arg, "mode", "show untracked files, optional modes: all, normal, no. (Default: all)", PARSE_OPT_OPTARG, NULL, (intptr_t)"all" },

Makes sense; thanks.

I however wonder if we have an opportunity for even more unifying these
two arrays, typing the same thing only once.

Re: [PATCH 7/7] git-tag.txt: list all modes in the description

[Junio C Hamano]

Michael J Gruber <git@drmicha.warpmail.net> writes:

> Currently, the description sounds as if it applied always, but most of
> its content is true in "create tag mode" only.
>
> Make this clearer by listing all modes and qualifying the main part.
>
> Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>

Thanks for noticing; I agree with the basic idea.

> diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
> index 8b169e3..c503f60 100644
> --- a/Documentation/git-tag.txt
> +++ b/Documentation/git-tag.txt
> @@ -18,7 +18,7 @@ SYNOPSIS
> ...
> -Adds a tag reference in `.git/refs/tags/`.
> +Without `-d/-l/-v`: Adds a tag reference in `.git/refs/tags/`.

But this leaves the reader in suspense what these three exceptions are for
after finishing the first sentence.  How about rewording like this?

    Add a tag reference in `.git/refs/tags/`, unless `-d/-l/-v` is given
    to delete, list or verify.

Then we don't need to repeat these three

    With `-d`: Deletes a tag.

    With `-l`: List tags.

    With `-v`: Verify tags.

that the readers would see in OPTIONS section fairly soon.

Re: [PATCH 4/7] merge,tag: describe -m just like commit

[Junio C Hamano]

Michael J Gruber <git@drmicha.warpmail.net> writes:

> This also removes the misleading "if any" which sounds as if omitting
> "-m" would omit the commmit message. (It meant to mean "if a merge
> commit is created at all".)

Hmph, then don't we want to keep that in your clearer form, i.e.

	specify merge commit message (if a merge is created at all)

An option is by definition to _specify_ something, "specify" is a waste of
space in a description of an option.  E.g. in patch 3/7, --template option
is described as "directory from which templates will be used", and not
"specify the directory from which...".

Re: [PATCH 2/7] push: describe --porcelain just like commit and status

[Sverre Rabbelier]

Heya,

On Mon, Feb 14, 2011 at 20:53, Junio C Hamano <gitster@pobox.com> wrote:
> The option was meant to mean "output format for Porcelain script writers
> to stay machine readable" but it can be misunderstood as "output format
> a Porcelain command would produce with chromes and glitters".

I've always thought this to be a rather awkward option name. If it had
been named '--plumbing' there'd be no room for such misunderstanding,
it outputs it a format suitable for use by, and as plumbing. Perhaps
something to remember for the future, or would we want to stay
consistent with the current --porcelain?

-- 
Cheers,

Sverre Rabbelier

Re: [PATCH 2/7] push: describe --porcelain just like commit and status

[Michael J Gruber]

Junio C Hamano venit, vidit, dixit 14.02.2011 20:53:
> Michael J Gruber <git@drmicha.warpmail.net> writes:
> 
>> -		OPT_BIT( 0,  "porcelain", &flags, "machine-readable output", TRANSPORT_PUSH_PORCELAIN),
>> +		OPT_BIT( 0,  "porcelain", &flags, "show porcelain output format", TRANSPORT_PUSH_PORCELAIN),
> 
> Thanks, but I wonder if machine-readable is more descriptive than
> "porcelain output format", iow, updating commit/status may be better.
> 
> The option was meant to mean "output format for Porcelain script writers
> to stay machine readable" but it can be misunderstood as "output format
> a Porcelain command would produce with chromes and glitters".

I'm happy with that, too. Generally, I tried to go with the majority
with this unifying series. In fact, we've been unhappy with the name of
that option as well, but the usage text is easier to change.

Michael

Re: [PATCH 6/7] commit,status: describe -u likewise

[Michael J Gruber]

Junio C Hamano venit, vidit, dixit 14.02.2011 20:57:
> Michael J Gruber <git@drmicha.warpmail.net> writes:
> 
>> They differ by one character only. Being exactly equal should help
>> translations.
>>
>> Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
>> ---
>> diff --git a/builtin/commit.c b/builtin/commit.c
>> index 8a534de..ef2114b 100644
>> --- a/builtin/commit.c
>> +++ b/builtin/commit.c
>> @@ -150,7 +150,7 @@ static struct option builtin_commit_options[] = {
>> ...
>> -	{ OPTION_STRING, 'u', "untracked-files", &untracked_files_arg, "mode", "show untracked files, optional modes: all, normal, no (Default: all)", PARSE_OPT_OPTARG, NULL, (intptr_t)"all" },
>> +	{ OPTION_STRING, 'u', "untracked-files", &untracked_files_arg, "mode", "show untracked files, optional modes: all, normal, no. (Default: all)", PARSE_OPT_OPTARG, NULL, (intptr_t)"all" },
> 
> Makes sense; thanks.
> 
> I however wonder if we have an opportunity for even more unifying these
> two arrays, typing the same thing only once.
> 

I was surprised we have two arrays at all, "status" being "commit
--dry-run". I'll check whether we can remove redundancy without too much
effort.

Michael

Re: [PATCH 4/7] merge,tag: describe -m just like commit

[Michael J Gruber]

Junio C Hamano venit, vidit, dixit 14.02.2011 21:08:
> Michael J Gruber <git@drmicha.warpmail.net> writes:
> 
>> This also removes the misleading "if any" which sounds as if omitting
>> "-m" would omit the commmit message. (It meant to mean "if a merge
>> commit is created at all".)
> 
> Hmph, then don't we want to keep that in your clearer form, i.e.
> 
> 	specify merge commit message (if a merge is created at all)

Well, any option is effective only in the case when the command succeeds
- "commit -m msg" specifies only a message when a commit is created at
all, etc. So, it usually is a trivial remark. It is slightly different
for merge because merge may succeed by doing a fast-forward without
creating a merge commit, which is why I wrote "merge commit message".
So, the parenthetical remark would have to be "if a non-ff merge commit
is created". I'm afraid "merge created" alone would not convey this.

> An option is by definition to _specify_ something, "specify" is a waste of
> space in a description of an option.  E.g. in patch 3/7, --template option
> is described as "directory from which templates will be used", and not
> "specify the directory from which...".

Oh yes, I tried to refrain from mixing other clean-up tasks with the
unifying series, especially in the absence of (my knowledge about) an
option "style guide". If "--foo bar" specifies that "bar" is used as
"baz" then saying "--foo <BAR>: baz" is enough and c/should be the
general rule. I'd be happy to incorporate this.

Michael

Re: [PATCH 6/7] commit,status: describe -u likewise

[Jeff King]

On Tue, Feb 15, 2011 at 07:53:07AM +0100, Michael J Gruber wrote:

> > I however wonder if we have an opportunity for even more unifying
> > these two arrays, typing the same thing only once.
> 
> I was surprised we have two arrays at all, "status" being "commit
> --dry-run". I'll check whether we can remove redundancy without too
> much effort.

Hmm, not according to 9e4b7ab (git status: not "commit --dry-run"
anymore, 2009-08-15).

"Commit --dry-run" more-or-less runs status on the index that would be
committed. But it obviously takes a lot of options that status does not,
and in theory status could take options that "commit --dry-run" does
not (certainly its non-option arguments are different these days, but
parse_options doesn't care about that).

I said "in theory" because I have no idea if such options exist yet or
not. But probably any refactoring should pull out the common options
into a shared list, and not simply make commit a superset of the status
options.

-Peff

[PATCHv2 00/10] Cleaning up --help-all inconsistencies

[Michael J Gruber]

v2 incorporates the changes as discussed so far.
It comes with three bonus patches which enforce the use of lowercase
<identifiers> (as per CodingGuidelines) in command messages (usage).
Besides the guidelines, this is also the prevailing style in code.
Documentation is a different issue.

patches 1,3,5 are unchanged wrt v1.

The last 3 are divided according to the grep expressions which I used to
identify candidates.

Michael J Gruber (10):
  commit,tag: use same wording for -F
  commit,status: describe --porcelain just like push
  clone,init: describe --template using the same wording
  commit,merge,tag: describe -m likewise
  add: describe --patch like checkout, reset
  commit,status: describe -u likewise
  git-tag.txt: list all modes in the description
  Make <identifier> lowercase as per CodingGuidelines
  Make <identifier> lowercase as per CodingGuidelines
  Make <identifier> lowercase as per CodingGuidelines

 Documentation/git-tag.txt |   11 ++++++-----
 builtin/add.c             |    2 +-
 builtin/clone.c           |    4 ++--
 builtin/commit.c          |   22 +++++++++++-----------
 builtin/config.c          |    2 +-
 builtin/fast-export.c     |    4 ++--
 builtin/fetch.c           |    6 +++---
 builtin/init-db.c         |    2 +-
 builtin/merge.c           |    2 +-
 builtin/notes.c           |   16 ++++++++--------
 builtin/read-tree.c       |    4 ++--
 builtin/tag.c             |    6 +++---
 parse-options.h           |    2 +-
 t/t0040-parse-options.sh  |    2 +-
 test-parse-options.c      |    2 +-
 15 files changed, 44 insertions(+), 43 deletions(-)

-- 
1.7.4.1.74.gf39475.dirty

[PATCHv2 01/10] commit,tag: use same wording for -F

[Michael J Gruber]

Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
---
 builtin/commit.c |    2 +-
 builtin/tag.c    |    2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/builtin/commit.c b/builtin/commit.c
index 03cff5a..8a534de 100644
--- a/builtin/commit.c
+++ b/builtin/commit.c
@@ -118,7 +118,7 @@ static struct option builtin_commit_options[] = {
 	OPT__VERBOSE(&verbose, "show diff in commit message template"),
 
 	OPT_GROUP("Commit message options"),
-	OPT_FILENAME('F', "file", &logfile, "read log from file"),
+	OPT_FILENAME('F', "file", &logfile, "read message from file"),
 	OPT_STRING(0, "author", &force_author, "AUTHOR", "override author for commit"),
 	OPT_STRING(0, "date", &force_date, "DATE", "override date for commit"),
 	OPT_CALLBACK('m', "message", &message, "MESSAGE", "specify commit message", opt_parse_m),
diff --git a/builtin/tag.c b/builtin/tag.c
index aa1f87d..6408171 100644
--- a/builtin/tag.c
+++ b/builtin/tag.c
@@ -378,7 +378,7 @@ int cmd_tag(int argc, const char **argv, const char *prefix)
 					"annotated tag, needs a message"),
 		OPT_CALLBACK('m', NULL, &msg, "msg",
 			     "message for the tag", parse_msg_arg),
-		OPT_FILENAME('F', NULL, &msgfile, "message in a file"),
+		OPT_FILENAME('F', NULL, &msgfile, "read message from file"),
 		OPT_BOOLEAN('s', NULL, &sign, "annotated and GPG-signed tag"),
 		OPT_STRING('u', NULL, &keyid, "key-id",
 					"use another key to sign the tag"),
-- 
1.7.4.1.74.gf39475.dirty

[PATCHv2 02/10] commit,status: describe --porcelain just like push

[Michael J Gruber]

Push has the clearer description, so take that one for all.

Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
---
 builtin/commit.c |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/builtin/commit.c b/builtin/commit.c
index 8a534de..0245d9f 100644
--- a/builtin/commit.c
+++ b/builtin/commit.c
@@ -145,7 +145,7 @@ static struct option builtin_commit_options[] = {
 		    STATUS_FORMAT_SHORT),
 	OPT_BOOLEAN(0, "branch", &status_show_branch, "show branch information"),
 	OPT_SET_INT(0, "porcelain", &status_format,
-		    "show porcelain output format", STATUS_FORMAT_PORCELAIN),
+		    "machine-readable output", STATUS_FORMAT_PORCELAIN),
 	OPT_BOOLEAN('z', "null", &null_termination,
 		    "terminate entries with NUL"),
 	OPT_BOOLEAN(0, "amend", &amend, "amend previous commit"),
@@ -1092,7 +1092,7 @@ int cmd_status(int argc, const char **argv, const char *prefix)
 		OPT_BOOLEAN('b', "branch", &status_show_branch,
 			    "show branch information"),
 		OPT_SET_INT(0, "porcelain", &status_format,
-			    "show porcelain output format",
+			    "machine-readable output",
 			    STATUS_FORMAT_PORCELAIN),
 		OPT_BOOLEAN('z', "null", &null_termination,
 			    "terminate entries with NUL"),
-- 
1.7.4.1.74.gf39475.dirty

[PATCHv2 03/10] clone,init: describe --template using the same wording

[Michael J Gruber]

This also corrects a wrong description for clone.

Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
---
 builtin/clone.c   |    4 ++--
 builtin/init-db.c |    2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/builtin/clone.c b/builtin/clone.c
index 82a6938..60d9a64 100644
--- a/builtin/clone.c
+++ b/builtin/clone.c
@@ -68,8 +68,8 @@ static struct option builtin_clone_options[] = {
 		    "initialize submodules in the clone"),
 	OPT_BOOLEAN(0, "recurse-submodules", &option_recursive,
 		    "initialize submodules in the clone"),
-	OPT_STRING(0, "template", &option_template, "path",
-		   "path the template repository"),
+	OPT_STRING(0, "template", &option_template, "template-directory",
+		   "directory from which templates will be used"),
 	OPT_STRING(0, "reference", &option_reference, "repo",
 		   "reference repository"),
 	OPT_STRING('o', "origin", &option_origin, "branch",
diff --git a/builtin/init-db.c b/builtin/init-db.c
index e3af9ea..4f5348e 100644
--- a/builtin/init-db.c
+++ b/builtin/init-db.c
@@ -419,7 +419,7 @@ int cmd_init_db(int argc, const char **argv, const char *prefix)
 	unsigned int flags = 0;
 	const struct option init_db_options[] = {
 		OPT_STRING(0, "template", &template_dir, "template-directory",
-				"provide the directory from which templates will be used"),
+				"directory from which templates will be used"),
 		OPT_SET_INT(0, "bare", &is_bare_repository_cfg,
 				"create a bare repository", 1),
 		{ OPTION_CALLBACK, 0, "shared", &init_shared_repository,
-- 
1.7.4.1.74.gf39475.dirty

[PATCHv2 04/10] commit,merge,tag: describe -m likewise

[Michael J Gruber]

This also removes the superfluous "specify" and rewords the misleading
"if any" which sounds as if omitting "-m" would omit the merge commit
message. (It means "if a merge commit is created at all".)

Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
---
 builtin/commit.c |    2 +-
 builtin/merge.c  |    4 ++--
 builtin/tag.c    |    4 ++--
 3 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/builtin/commit.c b/builtin/commit.c
index 0245d9f..0090571 100644
--- a/builtin/commit.c
+++ b/builtin/commit.c
@@ -121,7 +121,7 @@ static struct option builtin_commit_options[] = {
 	OPT_FILENAME('F', "file", &logfile, "read message from file"),
 	OPT_STRING(0, "author", &force_author, "AUTHOR", "override author for commit"),
 	OPT_STRING(0, "date", &force_date, "DATE", "override date for commit"),
-	OPT_CALLBACK('m', "message", &message, "MESSAGE", "specify commit message", opt_parse_m),
+	OPT_CALLBACK('m', "message", &message, "MESSAGE", "commit message", opt_parse_m),
 	OPT_STRING('c', "reedit-message", &edit_message, "COMMIT", "reuse and edit message from specified commit"),
 	OPT_STRING('C', "reuse-message", &use_message, "COMMIT", "reuse message from specified commit"),
 	OPT_STRING(0, "fixup", &fixup_message, "COMMIT", "use autosquash formatted message to fixup specified commit"),
diff --git a/builtin/merge.c b/builtin/merge.c
index 9403747..8c58c3c 100644
--- a/builtin/merge.c
+++ b/builtin/merge.c
@@ -194,8 +194,8 @@ static struct option builtin_merge_options[] = {
 		"merge strategy to use", option_parse_strategy),
 	OPT_CALLBACK('X', "strategy-option", &xopts, "option=value",
 		"option for selected merge strategy", option_parse_x),
-	OPT_CALLBACK('m', "message", &merge_msg, "message",
-		"message to be used for the merge commit (if any)",
+	OPT_CALLBACK('m', "message", &merge_msg, "MESSAGE",
+		"merge commit message (for a non-fast-forward merge)",
 		option_parse_message),
 	OPT__VERBOSITY(&verbosity),
 	OPT_BOOLEAN(0, "abort", &abort_current_merge,
diff --git a/builtin/tag.c b/builtin/tag.c
index 6408171..246a2bc 100644
--- a/builtin/tag.c
+++ b/builtin/tag.c
@@ -376,8 +376,8 @@ int cmd_tag(int argc, const char **argv, const char *prefix)
 		OPT_GROUP("Tag creation options"),
 		OPT_BOOLEAN('a', NULL, &annotate,
 					"annotated tag, needs a message"),
-		OPT_CALLBACK('m', NULL, &msg, "msg",
-			     "message for the tag", parse_msg_arg),
+		OPT_CALLBACK('m', NULL, &msg, "MESSAGE",
+			     "tag message", parse_msg_arg),
 		OPT_FILENAME('F', NULL, &msgfile, "read message from file"),
 		OPT_BOOLEAN('s', NULL, &sign, "annotated and GPG-signed tag"),
 		OPT_STRING('u', NULL, &keyid, "key-id",
-- 
1.7.4.1.74.gf39475.dirty

[PATCHv2 05/10] add: describe --patch like checkout, reset

[Michael J Gruber]

Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
---
 builtin/add.c |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/builtin/add.c b/builtin/add.c
index 5f817ad..f8e51f9 100644
--- a/builtin/add.c
+++ b/builtin/add.c
@@ -317,7 +317,7 @@ static struct option builtin_add_options[] = {
 	OPT__VERBOSE(&verbose, "be verbose"),
 	OPT_GROUP(""),
 	OPT_BOOLEAN('i', "interactive", &add_interactive, "interactive picking"),
-	OPT_BOOLEAN('p', "patch", &patch_interactive, "interactive patching"),
+	OPT_BOOLEAN('p', "patch", &patch_interactive, "select hunks interactively"),
 	OPT_BOOLEAN('e', "edit", &edit_interactive, "edit current diff and apply"),
 	OPT__FORCE(&ignored_too, "allow adding otherwise ignored files"),
 	OPT_BOOLEAN('u', "update", &take_worktree_changes, "update tracked files"),
-- 
1.7.4.1.74.gf39475.dirty

[PATCHv2 06/10] commit,status: describe -u likewise

[Michael J Gruber]

They differ by one character only. Being exactly equal should help
translations.

Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
---
 builtin/commit.c |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/builtin/commit.c b/builtin/commit.c
index 0090571..d7f55e3 100644
--- a/builtin/commit.c
+++ b/builtin/commit.c
@@ -150,7 +150,7 @@ static struct option builtin_commit_options[] = {
 		    "terminate entries with NUL"),
 	OPT_BOOLEAN(0, "amend", &amend, "amend previous commit"),
 	OPT_BOOLEAN(0, "no-post-rewrite", &no_post_rewrite, "bypass post-rewrite hook"),
-	{ OPTION_STRING, 'u', "untracked-files", &untracked_files_arg, "mode", "show untracked files, optional modes: all, normal, no (Default: all)", PARSE_OPT_OPTARG, NULL, (intptr_t)"all" },
+	{ OPTION_STRING, 'u', "untracked-files", &untracked_files_arg, "mode", "show untracked files, optional modes: all, normal, no. (Default: all)", PARSE_OPT_OPTARG, NULL, (intptr_t)"all" },
 	/* end commit contents options */
 
 	{ OPTION_BOOLEAN, 0, "allow-empty", &allow_empty, NULL,
-- 
1.7.4.1.74.gf39475.dirty

[PATCHv2 07/10] git-tag.txt: list all modes in the description

[Michael J Gruber]

Currently, the description sounds as if it applied always, but most of
its content is true in "create tag mode" only.

Make this clearer by listing all modes upfront.

Also, sneak in some linguistic improvements and make it clearer that
lightweight tags are "created" because "written" may be misread as
"are output".

Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
---
 Documentation/git-tag.txt |   11 ++++++-----
 1 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
index 8b169e3..65f76c5 100644
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@ -18,21 +18,22 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-Adds a tag reference in `.git/refs/tags/`.
+Add a tag reference in `.git/refs/tags/`, unless `-d/-l/-v` is given
+to delete, list or verify tags.
 
-Unless `-f` is given, the tag must not yet exist in
+Unless `-f` is given, the tag to be created must not yet exist in the
 `.git/refs/tags/` directory.
 
 If one of `-a`, `-s`, or `-u <key-id>` is passed, the command
-creates a 'tag' object, and requires the tag message.  Unless
+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>`
 are absent, `-a` is implied.
 
-Otherwise just the SHA1 object name of the commit object is
-written (i.e. a lightweight tag).
+Otherwise just a tag reference for the SHA1 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
-- 
1.7.4.1.74.gf39475.dirty

[PATCHv2 08/10] Make <identifier> lowercase as per CodingGuidelines

[Michael J Gruber]

parse-options part

Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
---
 parse-options.h |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/parse-options.h b/parse-options.h
index 31ec5d2..d1b12fe 100644
--- a/parse-options.h
+++ b/parse-options.h
@@ -141,7 +141,7 @@ struct option {
 	{ OPTION_NUMBER, 0, NULL, (v), NULL, (h), \
 	  PARSE_OPT_NOARG | PARSE_OPT_NONEG, (f) }
 #define OPT_FILENAME(s, l, v, h)    { OPTION_FILENAME, (s), (l), (v), \
-				       "FILE", (h) }
+				       "file", (h) }
 #define OPT_COLOR_FLAG(s, l, v, h) \
 	{ OPTION_CALLBACK, (s), (l), (v), "when", (h), PARSE_OPT_OPTARG, \
 		parse_opt_color_flag_cb, (intptr_t)"always" }
-- 
1.7.4.1.74.gf39475.dirty

[PATCHv2 09/10] Make <identifier> lowercase as per CodingGuidelines

[Michael J Gruber]

*.c part for matches with '"[A-Z]+"'.

Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
---
 builtin/commit.c      |   14 +++++++-------
 builtin/config.c      |    2 +-
 builtin/fast-export.c |    4 ++--
 builtin/fetch.c       |    6 +++---
 builtin/merge.c       |    2 +-
 builtin/notes.c       |   16 ++++++++--------
 builtin/read-tree.c   |    4 ++--
 builtin/tag.c         |    2 +-
 8 files changed, 25 insertions(+), 25 deletions(-)

diff --git a/builtin/commit.c b/builtin/commit.c
index d7f55e3..355b2cb 100644
--- a/builtin/commit.c
+++ b/builtin/commit.c
@@ -119,13 +119,13 @@ static struct option builtin_commit_options[] = {
 
 	OPT_GROUP("Commit message options"),
 	OPT_FILENAME('F', "file", &logfile, "read message from file"),
-	OPT_STRING(0, "author", &force_author, "AUTHOR", "override author for commit"),
-	OPT_STRING(0, "date", &force_date, "DATE", "override date for commit"),
-	OPT_CALLBACK('m', "message", &message, "MESSAGE", "commit message", opt_parse_m),
-	OPT_STRING('c', "reedit-message", &edit_message, "COMMIT", "reuse and edit message from specified commit"),
-	OPT_STRING('C', "reuse-message", &use_message, "COMMIT", "reuse message from specified commit"),
-	OPT_STRING(0, "fixup", &fixup_message, "COMMIT", "use autosquash formatted message to fixup specified commit"),
-	OPT_STRING(0, "squash", &squash_message, "COMMIT", "use autosquash formatted message to squash specified commit"),
+	OPT_STRING(0, "author", &force_author, "author", "override author for commit"),
+	OPT_STRING(0, "date", &force_date, "date", "override date for commit"),
+	OPT_CALLBACK('m', "message", &message, "message", "commit message", opt_parse_m),
+	OPT_STRING('c', "reedit-message", &edit_message, "commit", "reuse and edit message from specified commit"),
+	OPT_STRING('C', "reuse-message", &use_message, "commit", "reuse message from specified commit"),
+	OPT_STRING(0, "fixup", &fixup_message, "commit", "use autosquash formatted message to fixup specified commit"),
+	OPT_STRING(0, "squash", &squash_message, "commit", "use autosquash formatted message to squash specified commit"),
 	OPT_BOOLEAN(0, "reset-author", &renew_authorship, "the commit is authored by me now (used with -C-c/--amend)"),
 	OPT_BOOLEAN('s', "signoff", &signoff, "add Signed-off-by:"),
 	OPT_FILENAME('t', "template", &template_file, "use specified template file"),
diff --git a/builtin/config.c b/builtin/config.c
index ca4a0db..b8b18e3 100644
--- a/builtin/config.c
+++ b/builtin/config.c
@@ -52,7 +52,7 @@ static struct option builtin_config_options[] = {
 	OPT_BOOLEAN(0, "global", &use_global_config, "use global config file"),
 	OPT_BOOLEAN(0, "system", &use_system_config, "use system config file"),
 	OPT_BOOLEAN(0, "local", &use_local_config, "use repository config file"),
-	OPT_STRING('f', "file", &given_config_file, "FILE", "use given config file"),
+	OPT_STRING('f', "file", &given_config_file, "file", "use given config file"),
 	OPT_GROUP("Action"),
 	OPT_BIT(0, "get", &actions, "get value: name [value-regex]", ACTION_GET),
 	OPT_BIT(0, "get-all", &actions, "get all values: key [value-regex]", ACTION_GET_ALL),
diff --git a/builtin/fast-export.c b/builtin/fast-export.c
index ba57457..daf1945 100644
--- a/builtin/fast-export.c
+++ b/builtin/fast-export.c
@@ -619,9 +619,9 @@ int cmd_fast_export(int argc, const char **argv, const char *prefix)
 		OPT_CALLBACK(0, "tag-of-filtered-object", &tag_of_filtered_mode, "mode",
 			     "select handling of tags that tag filtered objects",
 			     parse_opt_tag_of_filtered_mode),
-		OPT_STRING(0, "export-marks", &export_filename, "FILE",
+		OPT_STRING(0, "export-marks", &export_filename, "file",
 			     "Dump marks to this file"),
-		OPT_STRING(0, "import-marks", &import_filename, "FILE",
+		OPT_STRING(0, "import-marks", &import_filename, "file",
 			     "Import marks from this file"),
 		OPT_BOOLEAN(0, "fake-missing-tagger", &fake_missing_tagger,
 			     "Fake a tagger when tags lack one"),
diff --git a/builtin/fetch.c b/builtin/fetch.c
index 357f3cd..7efecfe 100644
--- a/builtin/fetch.c
+++ b/builtin/fetch.c
@@ -49,7 +49,7 @@ static struct option builtin_fetch_options[] = {
 		    "fetch from all remotes"),
 	OPT_BOOLEAN('a', "append", &append,
 		    "append to .git/FETCH_HEAD instead of overwriting"),
-	OPT_STRING(0, "upload-pack", &upload_pack, "PATH",
+	OPT_STRING(0, "upload-pack", &upload_pack, "path",
 		   "path to upload pack on remote end"),
 	OPT__FORCE(&force, "force overwrite of local branch"),
 	OPT_BOOLEAN('m', "multiple", &multiple,
@@ -69,9 +69,9 @@ static struct option builtin_fetch_options[] = {
 	OPT_BOOLEAN('u', "update-head-ok", &update_head_ok,
 		    "allow updating of HEAD ref"),
 	OPT_BOOLEAN(0, "progress", &progress, "force progress reporting"),
-	OPT_STRING(0, "depth", &depth, "DEPTH",
+	OPT_STRING(0, "depth", &depth, "depth",
 		   "deepen history of shallow clone"),
-	{ OPTION_STRING, 0, "submodule-prefix", &submodule_prefix, "DIR",
+	{ OPTION_STRING, 0, "submodule-prefix", &submodule_prefix, "dir",
 		   "prepend this to submodule path output", PARSE_OPT_HIDDEN },
 	OPT_END()
 };
diff --git a/builtin/merge.c b/builtin/merge.c
index 8c58c3c..0710281 100644
--- a/builtin/merge.c
+++ b/builtin/merge.c
@@ -194,7 +194,7 @@ static struct option builtin_merge_options[] = {
 		"merge strategy to use", option_parse_strategy),
 	OPT_CALLBACK('X', "strategy-option", &xopts, "option=value",
 		"option for selected merge strategy", option_parse_x),
-	OPT_CALLBACK('m', "message", &merge_msg, "MESSAGE",
+	OPT_CALLBACK('m', "message", &merge_msg, "message",
 		"merge commit message (for a non-fast-forward merge)",
 		option_parse_message),
 	OPT__VERBOSITY(&verbosity),
diff --git a/builtin/notes.c b/builtin/notes.c
index 4d5556e..0aab150 100644
--- a/builtin/notes.c
+++ b/builtin/notes.c
@@ -537,16 +537,16 @@ static int add(int argc, const char **argv, const char *prefix)
 	const unsigned char *note;
 	struct msg_arg msg = { 0, 0, STRBUF_INIT };
 	struct option options[] = {
-		{ OPTION_CALLBACK, 'm', "message", &msg, "MSG",
+		{ OPTION_CALLBACK, 'm', "message", &msg, "msg",
 			"note contents as a string", PARSE_OPT_NONEG,
 			parse_msg_arg},
-		{ OPTION_CALLBACK, 'F', "file", &msg, "FILE",
+		{ OPTION_CALLBACK, 'F', "file", &msg, "file",
 			"note contents in a file", PARSE_OPT_NONEG,
 			parse_file_arg},
-		{ OPTION_CALLBACK, 'c', "reedit-message", &msg, "OBJECT",
+		{ OPTION_CALLBACK, 'c', "reedit-message", &msg, "object",
 			"reuse and edit specified note object", PARSE_OPT_NONEG,
 			parse_reedit_arg},
-		{ OPTION_CALLBACK, 'C', "reuse-message", &msg, "OBJECT",
+		{ OPTION_CALLBACK, 'C', "reuse-message", &msg, "object",
 			"reuse specified note object", PARSE_OPT_NONEG,
 			parse_reuse_arg},
 		OPT__FORCE(&force, "replace existing notes"),
@@ -682,16 +682,16 @@ static int append_edit(int argc, const char **argv, const char *prefix)
 	const char * const *usage;
 	struct msg_arg msg = { 0, 0, STRBUF_INIT };
 	struct option options[] = {
-		{ OPTION_CALLBACK, 'm', "message", &msg, "MSG",
+		{ OPTION_CALLBACK, 'm', "message", &msg, "msg",
 			"note contents as a string", PARSE_OPT_NONEG,
 			parse_msg_arg},
-		{ OPTION_CALLBACK, 'F', "file", &msg, "FILE",
+		{ OPTION_CALLBACK, 'F', "file", &msg, "file",
 			"note contents in a file", PARSE_OPT_NONEG,
 			parse_file_arg},
-		{ OPTION_CALLBACK, 'c', "reedit-message", &msg, "OBJECT",
+		{ OPTION_CALLBACK, 'c', "reedit-message", &msg, "object",
 			"reuse and edit specified note object", PARSE_OPT_NONEG,
 			parse_reedit_arg},
-		{ OPTION_CALLBACK, 'C', "reuse-message", &msg, "OBJECT",
+		{ OPTION_CALLBACK, 'C', "reuse-message", &msg, "object",
 			"reuse specified note object", PARSE_OPT_NONEG,
 			parse_reuse_arg},
 		OPT_END()
diff --git a/builtin/read-tree.c b/builtin/read-tree.c
index 73c89ed..93c9281 100644
--- a/builtin/read-tree.c
+++ b/builtin/read-tree.c
@@ -104,8 +104,8 @@ int cmd_read_tree(int argc, const char **argv, const char *unused_prefix)
 	struct unpack_trees_options opts;
 	int prefix_set = 0;
 	const struct option read_tree_options[] = {
-		{ OPTION_CALLBACK, 0, "index-output", NULL, "FILE",
-		  "write resulting index to <FILE>",
+		{ OPTION_CALLBACK, 0, "index-output", NULL, "file",
+		  "write resulting index to <file>",
 		  PARSE_OPT_NONEG, index_output_cb },
 		OPT_SET_INT(0, "empty", &read_empty,
 			    "only empty the index", 1),
diff --git a/builtin/tag.c b/builtin/tag.c
index 246a2bc..7cf48ab 100644
--- a/builtin/tag.c
+++ b/builtin/tag.c
@@ -376,7 +376,7 @@ int cmd_tag(int argc, const char **argv, const char *prefix)
 		OPT_GROUP("Tag creation options"),
 		OPT_BOOLEAN('a', NULL, &annotate,
 					"annotated tag, needs a message"),
-		OPT_CALLBACK('m', NULL, &msg, "MESSAGE",
+		OPT_CALLBACK('m', NULL, &msg, "message",
 			     "tag message", parse_msg_arg),
 		OPT_FILENAME('F', NULL, &msgfile, "read message from file"),
 		OPT_BOOLEAN('s', NULL, &sign, "annotated and GPG-signed tag"),
-- 
1.7.4.1.74.gf39475.dirty

[PATCHv2 10/10] Make <identifier> lowercase as per CodingGuidelines

[Michael J Gruber]

*.c part for matches with '<[A-Z]+>' (and affected test).

Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
---
 t/t0040-parse-options.sh |    2 +-
 test-parse-options.c     |    2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/t/t0040-parse-options.sh b/t/t0040-parse-options.sh
index 2092450..ae26614 100755
--- a/t/t0040-parse-options.sh
+++ b/t/t0040-parse-options.sh
@@ -19,7 +19,7 @@ usage: test-parse-options <options>
     --set23               set integer to 23
     -t <time>             get timestamp of <time>
     -L, --length <str>    get length of <str>
-    -F, --file <FILE>     set file to <FILE>
+    -F, --file <file>     set file to <file>
 
 String options
     -s, --string <string>
diff --git a/test-parse-options.c b/test-parse-options.c
index 0828592..4e3710b 100644
--- a/test-parse-options.c
+++ b/test-parse-options.c
@@ -46,7 +46,7 @@ int main(int argc, const char **argv)
 		OPT_DATE('t', NULL, &timestamp, "get timestamp of <time>"),
 		OPT_CALLBACK('L', "length", &integer, "str",
 			"get length of <str>", length_callback),
-		OPT_FILENAME('F', "file", &file, "set file to <FILE>"),
+		OPT_FILENAME('F', "file", &file, "set file to <file>"),
 		OPT_GROUP("String options"),
 		OPT_STRING('s', "string", &string, "string", "get a string"),
 		OPT_STRING(0, "string2", &string, "str", "get another string"),
-- 
1.7.4.1.74.gf39475.dirty

Re: [PATCH 4/7] merge,tag: describe -m just like commit

[Junio C Hamano]

Michael J Gruber <git@drmicha.warpmail.net> writes:

> Well, any option is effective only in the case when the command succeeds
> - "commit -m msg" specifies only a message when a commit is created at
> all, etc. So, it usually is a trivial remark. It is slightly different
> for merge because merge may succeed by doing a fast-forward without
> creating a merge commit, which is why I wrote "merge commit message".
> So, the parenthetical remark would have to be "if a non-ff merge commit
> is created". I'm afraid "merge created" alone would not convey this.

Ok.  Thanks for clarifying the thinking behind it.

Re: [PATCHv2 00/10] Cleaning up --help-all inconsistencies

[Junio C Hamano]

Michael J Gruber <git@drmicha.warpmail.net> writes:

> v2 incorporates the changes as discussed so far.

Looked reasonable; thanks.

> It comes with three bonus patches which enforce the use of lowercase
> <identifiers> (as per CodingGuidelines) in command messages (usage).
>
> Besides the guidelines, this is also the prevailing style in code.

Not that I am opposed to this change, but I don't see anything that says
we want lower-case in CodingGuidelines. "Placeholders are enclosed in
angle brackets." is the only thing it says as far as I can tell.

So perhaps insert this before the last three patches.

-- >8 --
Subject: CodingGuidelines: downcase placeholders in usage messages

We accumulated some inconsistencies without an explicit guidance to spell
this out over time.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/CodingGuidelines |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index ba2006d..fe1c1e5 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -152,7 +152,7 @@ Writing Documentation:
  when writing or modifying command usage strings and synopsis sections
  in the manual pages:
 
- Placeholders are enclosed in angle brackets:
+ Placeholders are spelled in lowercase and enclosed in angle brackets:
    <file>
    --sort=<key>
    --abbrev[=<n>]

Re: [PATCHv2 00/10] Cleaning up --help-all inconsistencies

[Michael J Gruber]

Junio C Hamano venit, vidit, dixit 15.02.2011 20:02:
> Michael J Gruber <git@drmicha.warpmail.net> writes:
> 
>> v2 incorporates the changes as discussed so far.
> 
> Looked reasonable; thanks.
> 
>> It comes with three bonus patches which enforce the use of lowercase
>> <identifiers> (as per CodingGuidelines) in command messages (usage).
>>
>> Besides the guidelines, this is also the prevailing style in code.
> 
> Not that I am opposed to this change, but I don't see anything that says
> we want lower-case in CodingGuidelines. "Placeholders are enclosed in
> angle brackets." is the only thing it says as far as I can tell.

It's not expressed explicitly, but the examples there are all lowercase.
Your patch below makes it explicit.

Having a second look at documentation, there aren't many changes to do -
I would tend to leave things like <URL>, <FQDN>, possibly <UUID> (since
they are abbreviations) uppercase; unsure about <CVSROOT> (like the env
var). What do you think?

> So perhaps insert this before the last three patches.
> 
> -- >8 --
> Subject: CodingGuidelines: downcase placeholders in usage messages
> 
> We accumulated some inconsistencies without an explicit guidance to spell
> this out over time.
> 
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
>  Documentation/CodingGuidelines |    2 +-
>  1 files changed, 1 insertions(+), 1 deletions(-)
> 
> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
> index ba2006d..fe1c1e5 100644
> --- a/Documentation/CodingGuidelines
> +++ b/Documentation/CodingGuidelines
> @@ -152,7 +152,7 @@ Writing Documentation:
>   when writing or modifying command usage strings and synopsis sections
>   in the manual pages:
>  
> - Placeholders are enclosed in angle brackets:
> + Placeholders are spelled in lowercase and enclosed in angle brackets:
>     <file>
>     --sort=<key>
>     --abbrev[=<n>]

Re: [PATCHv2 00/10] Cleaning up --help-all inconsistencies

[Junio C Hamano]

Michael J Gruber <git@drmicha.warpmail.net> writes:

> Having a second look at documentation, there aren't many changes to do -
> I would tend to leave things like <URL>, <FQDN>, possibly <UUID> (since
> they are abbreviations) uppercase; unsure about <CVSROOT> (like the env
> var). What do you think?

The only ones in my "git grep '<[A-Z]*>' Documentation/" that look
offending are:

 - "option verbosity <N>" (git-remote-helpers)
 - "-r/--revision <ARG>" (git-svn)

and everything else looks like they should be left as they are.

[PATCH] Make <identifier> lowercase in Documentation

[Michael J Gruber]

Leaving uppercase abbreviations (e.g. URL) and an identifier named after
an upercase env variable (CVSROOT) in place, this adjusts the few
remaining cases and fixes an unidentified identifier along the way.

Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
---
 Documentation/git-remote-ext.txt     |   14 +++++++-------
 Documentation/git-remote-helpers.txt |    6 +++---
 Documentation/git-svn.txt            |    6 +++---
 3 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/Documentation/git-remote-ext.txt b/Documentation/git-remote-ext.txt
index 2d65cfe..68263a6 100644
--- a/Documentation/git-remote-ext.txt
+++ b/Documentation/git-remote-ext.txt
@@ -7,17 +7,17 @@ git-remote-ext - Bridge smart transport to external command.
 
 SYNOPSIS
 --------
-git remote add nick "ext::<command>[ <arguments>...]"
+git remote add <nick> "ext::<command>[ <arguments>...]"
 
 DESCRIPTION
 -----------
-This remote helper uses the specified 'program' to connect
+This remote helper uses the specified '<command>' to connect
 to a remote git server.
 
-Data written to stdin of this specified 'program' is assumed
+Data written to stdin of the specified '<command>' is assumed
 to be sent to a git:// server, git-upload-pack, git-receive-pack
 or git-upload-archive (depending on situation), and data read
-from stdout of this program is assumed to be received from
+from stdout of <command> is assumed to be received from
 the same service.
 
 Command and arguments are separated by an unescaped space.
@@ -40,7 +40,7 @@ The following sequences have a special meaning:
 	git wants to invoke.
 
 '%G' (must be the first characters in an argument)::
-	This argument will not be passed to 'program'. Instead, it
+	This argument will not be passed to '<command>'. Instead, it
 	will cause the helper to start by sending git:// service requests to
 	the remote side with the service field set to an appropriate value and
 	the repository field set to rest of the argument. Default is not to send
@@ -50,7 +50,7 @@ This is useful if remote side is git:// server accessed over
 some tunnel.
 
 '%V' (must be first characters in argument)::
-	This argument will not be passed to 'program'. Instead it sets
+	This argument will not be passed to '<command>'. Instead it sets
 	the vhost field in the git:// service request (to rest of the argument).
 	Default is not to send vhost in such request (if sent).
 
@@ -76,7 +76,7 @@ EXAMPLES:
 ---------
 This remote helper is transparently used by git when
 you use commands such as "git fetch <URL>", "git clone <URL>",
-, "git push <URL>" or "git remote add nick <URL>", where <URL>
+, "git push <URL>" or "git remote add <nick> <URL>", where <URL>
 begins with `ext::`.  Examples:
 
 "ext::ssh -i /home/foo/.ssh/somekey user&#64;host.example %S 'foo/repo'"::
diff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt
index 3a23477..51de895 100644
--- a/Documentation/git-remote-helpers.txt
+++ b/Documentation/git-remote-helpers.txt
@@ -201,12 +201,12 @@ REF LIST ATTRIBUTES
 
 OPTIONS
 -------
-'option verbosity' <N>::
+'option verbosity' <n>::
 	Changes the verbosity of messages displayed by the helper.
-	A value of 0 for N means that processes operate
+	A value of 0 for <n> means that processes operate
 	quietly, and the helper produces only error output.
 	1 is the default level of verbosity, and higher values
-	of N correspond to the number of -v flags passed on the
+	of <n> correspond to the number of -v flags passed on the
 	command line.
 
 'option progress' \{'true'|'false'\}::
diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index 0ade2ce..e161a40 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -66,7 +66,7 @@ COMMANDS
 	Set the 'rewriteRoot' option in the [svn-remote] config.
 --rewrite-uuid=<UUID>;;
 	Set the 'rewriteUUID' option in the [svn-remote] config.
---username=<USER>;;
+--username=<user>;;
 	For transports that SVN handles authentication for (http,
 	https, and plain svn), specify the username.  For other
 	transports (eg svn+ssh://), you must include the username in
@@ -443,8 +443,8 @@ OPTIONS
 	Only used with the 'init' command.
 	These are passed directly to 'git init'.
 
--r <ARG>::
---revision <ARG>::
+-r <arg>::
+--revision <arg>::
 	   Used with the 'fetch' command.
 +
 This allows revision ranges for partial/cauterized history
-- 
1.7.4.1.74.gf39475.dirty