[PATCH 0/7] add description parameter to standard option macros

[PATCH 0/7] add description parameter to standard option macros

[René Scharfe]

This patch series is meant to improve the command line help texts
for standard options.

The first three patches add a description parameter to three helper
macros.  This allows command specific help texts to be defined for them
instead of enforcing ones that just repeat the option name.

	[PATCH 1/7] add description parameter to OPT__VERBOSE
	[PATCH 2/7] add description parameter to OPT__DRY_RUN
	[PATCH 3/7] add description parameter to OPT__QUIET

The next patch adds a similar helper macro for -f/--force.  It makes
it easier to define such an option in a consistent way.

	[PATCH 4/7] add OPT__FORCE

The last three patches depend on the first one and replace the standard
help text with a (hopefully) better explanation.

	[PATCH 5/7] archive: improve --verbose description
	[PATCH 6/7] branch: improve --verbose description
	[PATCH 7/7] verify-tag: document --verbose

Further patches to improve the remaining occurrences of "be verbose"
etc. are encouraged. :-)

 Documentation/git-verify-tag.txt              |    4 ++++
 Documentation/technical/api-parse-options.txt |    9 ++++++---
 archive.c                                     |    2 +-
 builtin/add.c                                 |    6 +++---
 builtin/apply.c                               |    2 +-
 builtin/branch.c                              |    5 +++--
 builtin/checkout-index.c                      |    5 ++---
 builtin/checkout.c                            |    4 ++--
 builtin/clean.c                               |    6 +++---
 builtin/commit.c                              |    6 +++---
 builtin/count-objects.c                       |    2 +-
 builtin/fetch.c                               |    3 +--
 builtin/fsck.c                                |    2 +-
 builtin/gc.c                                  |    2 +-
 builtin/grep.c                                |    4 ++--
 builtin/log.c                                 |    2 +-
 builtin/merge-file.c                          |    2 +-
 builtin/mv.c                                  |    4 ++--
 builtin/notes.c                               |    9 ++++-----
 builtin/prune.c                               |    5 ++---
 builtin/read-tree.c                           |    2 +-
 builtin/remote.c                              |    4 ++--
 builtin/reset.c                               |    2 +-
 builtin/rm.c                                  |    6 +++---
 builtin/show-ref.c                            |    2 +-
 builtin/symbolic-ref.c                        |    2 +-
 builtin/tag.c                                 |    2 +-
 builtin/update-server-info.c                  |    3 +--
 builtin/verify-tag.c                          |    2 +-
 parse-options.h                               |    7 ++++---
 test-parse-options.c                          |    6 +++---
 test-sha1.sh                                  |   14 ++++++++------
 32 files changed, 71 insertions(+), 65 deletions(-)

[PATCH 2/7] add description parameter to OPT__DRY_RUN

[René Scharfe]

Allows better help text to be defined than "dry run".  Also make use
of the macro in places that already had a different description.  No
object code changes intended.

Signed-off-by: Rene Scharfe <rene.scharfe@lsrfire.ath.cx>
---
 Documentation/technical/api-parse-options.txt |    2 +-
 builtin/add.c                                 |    2 +-
 builtin/clean.c                               |    2 +-
 builtin/mv.c                                  |    2 +-
 builtin/notes.c                               |    3 +--
 builtin/prune.c                               |    3 +--
 builtin/remote.c                              |    2 +-
 builtin/rm.c                                  |    2 +-
 parse-options.h                               |    2 +-
 test-parse-options.c                          |    2 +-
 10 files changed, 10 insertions(+), 12 deletions(-)

diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt
index 969489b..00c447c 100644
--- a/Documentation/technical/api-parse-options.txt
+++ b/Documentation/technical/api-parse-options.txt
@@ -118,7 +118,7 @@ There are some macros to easily define options:
 `OPT__COLOR(&int_var, description)`::
 	Add `\--color[=<when>]` and `--no-color`.
 
-`OPT__DRY_RUN(&int_var)`::
+`OPT__DRY_RUN(&int_var, description)`::
 	Add `-n, \--dry-run`.
 
 `OPT__QUIET(&int_var)`::
diff --git a/builtin/add.c b/builtin/add.c
index fbf1403..9625cee 100644
--- a/builtin/add.c
+++ b/builtin/add.c
@@ -313,7 +313,7 @@ static int verbose = 0, show_only = 0, ignored_too = 0, refresh_only = 0;
 static int ignore_add_errors, addremove, intent_to_add, ignore_missing = 0;
 
 static struct option builtin_add_options[] = {
-	OPT__DRY_RUN(&show_only),
+	OPT__DRY_RUN(&show_only, "dry run"),
 	OPT__VERBOSE(&verbose, "be verbose"),
 	OPT_GROUP(""),
 	OPT_BOOLEAN('i', "interactive", &add_interactive, "interactive picking"),
diff --git a/builtin/clean.c b/builtin/clean.c
index c8798f5..17ecbe6 100644
--- a/builtin/clean.c
+++ b/builtin/clean.c
@@ -49,7 +49,7 @@ int cmd_clean(int argc, const char **argv, const char *prefix)
 	char *seen = NULL;
 	struct option options[] = {
 		OPT__QUIET(&quiet),
-		OPT__DRY_RUN(&show_only),
+		OPT__DRY_RUN(&show_only, "dry run"),
 		OPT_BOOLEAN('f', "force", &force, "force"),
 		OPT_BOOLEAN('d', NULL, &remove_directories,
 				"remove whole directories"),
diff --git a/builtin/mv.c b/builtin/mv.c
index cdbb094..8677bd2 100644
--- a/builtin/mv.c
+++ b/builtin/mv.c
@@ -55,7 +55,7 @@ int cmd_mv(int argc, const char **argv, const char *prefix)
 	int i, newfd;
 	int verbose = 0, show_only = 0, force = 0, ignore_errors = 0;
 	struct option builtin_mv_options[] = {
-		OPT__DRY_RUN(&show_only),
+		OPT__DRY_RUN(&show_only, "dry run"),
 		OPT_BOOLEAN('f', "force", &force, "force move/rename even if target exists"),
 		OPT_BOOLEAN('k', NULL, &ignore_errors, "skip move/rename errors"),
 		OPT_END(),
diff --git a/builtin/notes.c b/builtin/notes.c
index e0a1f62..2ab070f 100644
--- a/builtin/notes.c
+++ b/builtin/notes.c
@@ -804,8 +804,7 @@ static int prune(int argc, const char **argv, const char *prefix)
 	struct notes_tree *t;
 	int show_only = 0, verbose = 0;
 	struct option options[] = {
-		OPT_BOOLEAN('n', "dry-run", &show_only,
-			    "do not remove, show only"),
+		OPT__DRY_RUN(&show_only, "do not remove, show only"),
 		OPT__VERBOSE(&verbose, "report pruned notes"),
 		OPT_END()
 	};
diff --git a/builtin/prune.c b/builtin/prune.c
index 8b770af..e65690b 100644
--- a/builtin/prune.c
+++ b/builtin/prune.c
@@ -125,8 +125,7 @@ int cmd_prune(int argc, const char **argv, const char *prefix)
 {
 	struct rev_info revs;
 	const struct option options[] = {
-		OPT_BOOLEAN('n', "dry-run", &show_only,
-			    "do not remove, show only"),
+		OPT__DRY_RUN(&show_only, "do not remove, show only"),
 		OPT__VERBOSE(&verbose, "report pruned objects"),
 		OPT_DATE(0, "expire", &expire,
 			 "expire objects older than <time>"),
diff --git a/builtin/remote.c b/builtin/remote.c
index b944b91..30b9922 100644
--- a/builtin/remote.c
+++ b/builtin/remote.c
@@ -1200,7 +1200,7 @@ static int prune(int argc, const char **argv)
 {
 	int dry_run = 0, result = 0;
 	struct option options[] = {
-		OPT__DRY_RUN(&dry_run),
+		OPT__DRY_RUN(&dry_run, "dry run"),
 		OPT_END()
 	};
 
diff --git a/builtin/rm.c b/builtin/rm.c
index f3772c8..26b7412 100644
--- a/builtin/rm.c
+++ b/builtin/rm.c
@@ -139,7 +139,7 @@ static int show_only = 0, force = 0, index_only = 0, recursive = 0, quiet = 0;
 static int ignore_unmatch = 0;
 
 static struct option builtin_rm_options[] = {
-	OPT__DRY_RUN(&show_only),
+	OPT__DRY_RUN(&show_only, "dry run"),
 	OPT__QUIET(&quiet),
 	OPT_BOOLEAN( 0 , "cached",         &index_only, "only remove from the index"),
 	OPT_BOOLEAN('f', "force",          &force,      "override the up-to-date check"),
diff --git a/parse-options.h b/parse-options.h
index 14918b1..69ce094 100644
--- a/parse-options.h
+++ b/parse-options.h
@@ -205,7 +205,7 @@ extern int parse_opt_tertiary(const struct option *, const char *, int);
 	  PARSE_OPT_NOARG, &parse_opt_verbosity_cb, 0 }, \
 	{ OPTION_CALLBACK, 'q', "quiet", (var), NULL, "be more quiet", \
 	  PARSE_OPT_NOARG, &parse_opt_verbosity_cb, 0 }
-#define OPT__DRY_RUN(var)  OPT_BOOLEAN('n', "dry-run", (var), "dry run")
+#define OPT__DRY_RUN(var, h)  OPT_BOOLEAN('n', "dry-run", (var), (h))
 #define OPT__ABBREV(var)  \
 	{ OPTION_CALLBACK, 0, "abbrev", (var), "n", \
 	  "use <n> digits to display SHA-1s", \
diff --git a/test-parse-options.c b/test-parse-options.c
index bd7b8a4..cddd106 100644
--- a/test-parse-options.c
+++ b/test-parse-options.c
@@ -67,7 +67,7 @@ int main(int argc, const char **argv)
 		OPT_GROUP("Standard options"),
 		OPT__ABBREV(&abbrev),
 		OPT__VERBOSE(&verbose, "be verbose"),
-		OPT__DRY_RUN(&dry_run),
+		OPT__DRY_RUN(&dry_run, "dry run"),
 		OPT__QUIET(&quiet),
 		OPT_END(),
 	};
-- 
1.7.3

[PATCH 3/7] add description parameter to OPT__QUIET

[René Scharfe]

Allows better help text to be defined than "be quiet".  Also make use
of the macro in a place that already had a different description.  No
object code changes intended.

Signed-off-by: Rene Scharfe <rene.scharfe@lsrfire.ath.cx>
---
 Documentation/technical/api-parse-options.txt |    2 +-
 builtin/checkout-index.c                      |    2 +-
 builtin/checkout.c                            |    2 +-
 builtin/clean.c                               |    2 +-
 builtin/commit.c                              |    2 +-
 builtin/gc.c                                  |    2 +-
 builtin/grep.c                                |    4 ++--
 builtin/merge-file.c                          |    2 +-
 builtin/reset.c                               |    2 +-
 builtin/rm.c                                  |    2 +-
 builtin/show-ref.c                            |    2 +-
 builtin/symbolic-ref.c                        |    2 +-
 parse-options.h                               |    2 +-
 test-parse-options.c                          |    2 +-
 14 files changed, 15 insertions(+), 15 deletions(-)

diff --git a/Documentation/technical/api-parse-options.txt
b/Documentation/technical/api-parse-options.txt
index 00c447c..248a66d 100644
--- a/Documentation/technical/api-parse-options.txt
+++ b/Documentation/technical/api-parse-options.txt
@@ -121,7 +121,7 @@ There are some macros to easily define options:
 `OPT__DRY_RUN(&int_var, description)`::
 	Add `-n, \--dry-run`.

-`OPT__QUIET(&int_var)`::
+`OPT__QUIET(&int_var, description)`::
 	Add `-q, \--quiet`.

 `OPT__VERBOSE(&int_var, description)`::
diff --git a/builtin/checkout-index.c b/builtin/checkout-index.c
index 65cbee0..7ba0913 100644
--- a/builtin/checkout-index.c
+++ b/builtin/checkout-index.c
@@ -219,7 +219,7 @@ int cmd_checkout_index(int argc, const char **argv,
const char *prefix)
 			"checks out all files in the index"),
 		OPT_BOOLEAN('f', "force", &force,
 			"forces overwrite of existing files"),
-		OPT__QUIET(&quiet),
+		OPT__QUIET(&quiet, "be quiet"),
 		OPT_BOOLEAN('n', "no-create", &not_new,
 			"don't checkout new files"),
 		{ OPTION_CALLBACK, 'u', "index", &newfd, NULL,
diff --git a/builtin/checkout.c b/builtin/checkout.c
index 9240faf..a952477 100644
--- a/builtin/checkout.c
+++ b/builtin/checkout.c
@@ -686,7 +686,7 @@ int cmd_checkout(int argc, const char **argv, const
char *prefix)
 	int patch_mode = 0;
 	int dwim_new_local_branch = 1;
 	struct option options[] = {
-		OPT__QUIET(&opts.quiet),
+		OPT__QUIET(&opts.quiet, "be quiet"),
 		OPT_STRING('b', NULL, &opts.new_branch, "branch",
 			   "create and checkout a new branch"),
 		OPT_STRING('B', NULL, &opts.new_branch_force, "branch",
diff --git a/builtin/clean.c b/builtin/clean.c
index 17ecbe6..449d2a3 100644
--- a/builtin/clean.c
+++ b/builtin/clean.c
@@ -48,7 +48,7 @@ int cmd_clean(int argc, const char **argv, const char
*prefix)
 	const char *qname;
 	char *seen = NULL;
 	struct option options[] = {
-		OPT__QUIET(&quiet),
+		OPT__QUIET(&quiet, "be quiet"),
 		OPT__DRY_RUN(&show_only, "dry run"),
 		OPT_BOOLEAN('f', "force", &force, "force"),
 		OPT_BOOLEAN('d', NULL, &remove_directories,
diff --git a/builtin/commit.c b/builtin/commit.c
index 9cbc4ea..97ae1bc 100644
--- a/builtin/commit.c
+++ b/builtin/commit.c
@@ -114,7 +114,7 @@ static int opt_parse_m(const struct option *opt,
const char *arg, int unset)
 }

 static struct option builtin_commit_options[] = {
-	OPT__QUIET(&quiet),
+	OPT__QUIET(&quiet, "be quiet"),
 	OPT__VERBOSE(&verbose, "be verbose"),

 	OPT_GROUP("Commit message options"),
diff --git a/builtin/gc.c b/builtin/gc.c
index c304638..8f67325 100644
--- a/builtin/gc.c
+++ b/builtin/gc.c
@@ -180,7 +180,7 @@ int cmd_gc(int argc, const char **argv, const char
*prefix)
 	char buf[80];

 	struct option builtin_gc_options[] = {
-		OPT__QUIET(&quiet),
+		OPT__QUIET(&quiet, "be quiet"),
 		{ OPTION_STRING, 0, "prune", &prune_expire, "date",
 			"prune unreferenced objects",
 			PARSE_OPT_OPTARG, NULL, (intptr_t)prune_expire },
diff --git a/builtin/grep.c b/builtin/grep.c
index 3d5f6ac..adb5424 100644
--- a/builtin/grep.c
+++ b/builtin/grep.c
@@ -915,8 +915,8 @@ int cmd_grep(int argc, const char **argv, const char
*prefix)
 		{ OPTION_CALLBACK, ')', NULL, &opt, NULL, "",
 		  PARSE_OPT_NOARG | PARSE_OPT_NONEG | PARSE_OPT_NODASH,
 		  close_callback },
-		OPT_BOOLEAN('q', "quiet", &opt.status_only,
-			    "indicate hit with exit status without output"),
+		OPT__QUIET(&opt.status_only,
+			   "indicate hit with exit status without output"),
 		OPT_BOOLEAN(0, "all-match", &opt.all_match,
 			"show only matches from files that match all patterns"),
 		OPT_GROUP(""),
diff --git a/builtin/merge-file.c b/builtin/merge-file.c
index b6664d4..58e4731 100644
--- a/builtin/merge-file.c
+++ b/builtin/merge-file.c
@@ -39,7 +39,7 @@ int cmd_merge_file(int argc, const char **argv, const
char *prefix)
 			    XDL_MERGE_FAVOR_UNION),
 		OPT_INTEGER(0, "marker-size", &xmp.marker_size,
 			    "for conflicts, use this marker size"),
-		OPT__QUIET(&quiet),
+		OPT__QUIET(&quiet, "be quiet"),
 		OPT_CALLBACK('L', NULL, names, "name",
 			     "set labels for file1/orig_file/file2", &label_cb),
 		OPT_END(),
diff --git a/builtin/reset.c b/builtin/reset.c
index 0037be4..d624207 100644
--- a/builtin/reset.c
+++ b/builtin/reset.c
@@ -243,7 +243,7 @@ int cmd_reset(int argc, const char **argv, const
char *prefix)
 	struct commit *commit;
 	char *reflog_action, msg[1024];
 	const struct option options[] = {
-		OPT__QUIET(&quiet),
+		OPT__QUIET(&quiet, "be quiet"),
 		OPT_SET_INT(0, "mixed", &reset_type,
 						"reset HEAD and index", MIXED),
 		OPT_SET_INT(0, "soft", &reset_type, "reset only HEAD", SOFT),
diff --git a/builtin/rm.c b/builtin/rm.c
index 26b7412..49461b6 100644
--- a/builtin/rm.c
+++ b/builtin/rm.c
@@ -140,7 +140,7 @@ static int ignore_unmatch = 0;

 static struct option builtin_rm_options[] = {
 	OPT__DRY_RUN(&show_only, "dry run"),
-	OPT__QUIET(&quiet),
+	OPT__QUIET(&quiet, "be quiet"),
 	OPT_BOOLEAN( 0 , "cached",         &index_only, "only remove from the
index"),
 	OPT_BOOLEAN('f', "force",          &force,      "override the
up-to-date check"),
 	OPT_BOOLEAN('r', NULL,             &recursive,  "allow recursive
removal"),
diff --git a/builtin/show-ref.c b/builtin/show-ref.c
index be9b512..6507f03 100644
--- a/builtin/show-ref.c
+++ b/builtin/show-ref.c
@@ -193,7 +193,7 @@ static const struct option show_ref_options[] = {
 	  "only show SHA1 hash using <n> digits",
 	  PARSE_OPT_OPTARG, &hash_callback },
 	OPT__ABBREV(&abbrev),
-	OPT__QUIET(&quiet),
+	OPT__QUIET(&quiet, "be quiet"),
 	{ OPTION_CALLBACK, 0, "exclude-existing", &exclude_existing_arg,
 	  "pattern", "show refs from stdin that aren't in local repository",
 	  PARSE_OPT_OPTARG | PARSE_OPT_NONEG, exclude_existing_callback },
diff --git a/builtin/symbolic-ref.c b/builtin/symbolic-ref.c
index ca855a5..1b28425 100644
--- a/builtin/symbolic-ref.c
+++ b/builtin/symbolic-ref.c
@@ -30,7 +30,7 @@ int cmd_symbolic_ref(int argc, const char **argv,
const char *prefix)
 	int quiet = 0;
 	const char *msg = NULL;
 	struct option options[] = {
-		OPT__QUIET(&quiet),
+		OPT__QUIET(&quiet, "be quiet"),
 		OPT_STRING('m', NULL, &msg, "reason", "reason of the update"),
 		OPT_END(),
 	};
diff --git a/parse-options.h b/parse-options.h
index 69ce094..3dd3a94 100644
--- a/parse-options.h
+++ b/parse-options.h
@@ -199,7 +199,7 @@ extern int parse_opt_with_commit(const struct option
*, const char *, int);
 extern int parse_opt_tertiary(const struct option *, const char *, int);

 #define OPT__VERBOSE(var, h)  OPT_BOOLEAN('v', "verbose", (var), (h))
-#define OPT__QUIET(var)    OPT_BOOLEAN('q', "quiet",   (var), "be quiet")
+#define OPT__QUIET(var, h)    OPT_BOOLEAN('q', "quiet",   (var), (h))
 #define OPT__VERBOSITY(var) \
 	{ OPTION_CALLBACK, 'v', "verbose", (var), NULL, "be more verbose", \
 	  PARSE_OPT_NOARG, &parse_opt_verbosity_cb, 0 }, \
diff --git a/test-parse-options.c b/test-parse-options.c
index cddd106..0828592 100644
--- a/test-parse-options.c
+++ b/test-parse-options.c
@@ -68,7 +68,7 @@ int main(int argc, const char **argv)
 		OPT__ABBREV(&abbrev),
 		OPT__VERBOSE(&verbose, "be verbose"),
 		OPT__DRY_RUN(&dry_run, "dry run"),
-		OPT__QUIET(&quiet),
+		OPT__QUIET(&quiet, "be quiet"),
 		OPT_END(),
 	};
 	int i;
-- 
1.7.3

[PATCH 4/7] add OPT__FORCE

[René Scharfe]

Add OPT__FORCE as a helper macro in the same spirit as OPT__VERBOSE
et.al. to simplify defining -f/--force options.

Signed-off-by: Rene Scharfe <rene.scharfe@lstfire.ath.cx>
---
 Documentation/technical/api-parse-options.txt |    3 +++
 builtin/add.c                                 |    2 +-
 builtin/branch.c                              |    2 +-
 builtin/checkout-index.c                      |    3 +--
 builtin/checkout.c                            |    2 +-
 builtin/clean.c                               |    2 +-
 builtin/fetch.c                               |    3 +--
 builtin/mv.c                                  |    2 +-
 builtin/notes.c                               |    4 ++--
 builtin/rm.c                                  |    2 +-
 builtin/tag.c                                 |    2 +-
 builtin/update-server-info.c                  |    3 +--
 parse-options.h                               |    1 +
 13 files changed, 16 insertions(+), 15 deletions(-)

diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt
index 248a66d..f6a4a36 100644
--- a/Documentation/technical/api-parse-options.txt
+++ b/Documentation/technical/api-parse-options.txt
@@ -121,6 +121,9 @@ There are some macros to easily define options:
 `OPT__DRY_RUN(&int_var, description)`::
 	Add `-n, \--dry-run`.
 
+`OPT__FORCE(&int_var, description)`::
+	Add `-f, \--force`.
+
 `OPT__QUIET(&int_var, description)`::
 	Add `-q, \--quiet`.
 
diff --git a/builtin/add.c b/builtin/add.c
index 9625cee..71f9b04 100644
--- a/builtin/add.c
+++ b/builtin/add.c
@@ -319,7 +319,7 @@ static struct option builtin_add_options[] = {
 	OPT_BOOLEAN('i', "interactive", &add_interactive, "interactive picking"),
 	OPT_BOOLEAN('p', "patch", &patch_interactive, "interactive patching"),
 	OPT_BOOLEAN('e', "edit", &edit_interactive, "edit current diff and apply"),
-	OPT_BOOLEAN('f', "force", &ignored_too, "allow adding otherwise ignored files"),
+	OPT__FORCE(&ignored_too, "allow adding otherwise ignored files"),
 	OPT_BOOLEAN('u', "update", &take_worktree_changes, "update tracked files"),
 	OPT_BOOLEAN('N', "intent-to-add", &intent_to_add, "record only the fact that the path will be added later"),
 	OPT_BOOLEAN('A', "all", &addremove, "add all, noticing removal of tracked files"),
diff --git a/builtin/branch.c b/builtin/branch.c
index 10788fc..e388edc 100644
--- a/builtin/branch.c
+++ b/builtin/branch.c
@@ -651,7 +651,7 @@ int cmd_branch(int argc, const char **argv, const char *prefix)
 		OPT_BIT('m', NULL, &rename, "move/rename a branch and its reflog", 1),
 		OPT_BIT('M', NULL, &rename, "move/rename a branch, even if target exists", 2),
 		OPT_BOOLEAN('l', NULL, &reflog, "create the branch's reflog"),
-		OPT_BOOLEAN('f', "force", &force_create, "force creation (when already exists)"),
+		OPT__FORCE(&force_create, "force creation (when already exists)"),
 		{
 			OPTION_CALLBACK, 0, "no-merged", &merge_filter_ref,
 			"commit", "print only not merged branches",
diff --git a/builtin/checkout-index.c b/builtin/checkout-index.c
index 7ba0913..91fb9bf 100644
--- a/builtin/checkout-index.c
+++ b/builtin/checkout-index.c
@@ -217,8 +217,7 @@ int cmd_checkout_index(int argc, const char **argv, const char *prefix)
 	struct option builtin_checkout_index_options[] = {
 		OPT_BOOLEAN('a', "all", &all,
 			"checks out all files in the index"),
-		OPT_BOOLEAN('f', "force", &force,
-			"forces overwrite of existing files"),
+		OPT__FORCE(&force, "forces overwrite of existing files"),
 		OPT__QUIET(&quiet, "be quiet"),
 		OPT_BOOLEAN('n', "no-create", &not_new,
 			"don't checkout new files"),
diff --git a/builtin/checkout.c b/builtin/checkout.c
index a952477..f275570 100644
--- a/builtin/checkout.c
+++ b/builtin/checkout.c
@@ -699,7 +699,7 @@ int cmd_checkout(int argc, const char **argv, const char *prefix)
 			    2),
 		OPT_SET_INT('3', "theirs", &opts.writeout_stage, "checkout their version for unmerged files",
 			    3),
-		OPT_BOOLEAN('f', "force", &opts.force, "force checkout (throw away local modifications)"),
+		OPT__FORCE(&opts.force, "force checkout (throw away local modifications)"),
 		OPT_BOOLEAN('m', "merge", &opts.merge, "perform a 3-way merge with the new branch"),
 		OPT_STRING(0, "conflict", &conflict_style, "style",
 			   "conflict style (merge or diff3)"),
diff --git a/builtin/clean.c b/builtin/clean.c
index 449d2a3..9146bf3 100644
--- a/builtin/clean.c
+++ b/builtin/clean.c
@@ -50,7 +50,7 @@ int cmd_clean(int argc, const char **argv, const char *prefix)
 	struct option options[] = {
 		OPT__QUIET(&quiet, "be quiet"),
 		OPT__DRY_RUN(&show_only, "dry run"),
-		OPT_BOOLEAN('f', "force", &force, "force"),
+		OPT__FORCE(&force, "force"),
 		OPT_BOOLEAN('d', NULL, &remove_directories,
 				"remove whole directories"),
 		{ OPTION_CALLBACK, 'e', "exclude", &exclude_list, "pattern",
diff --git a/builtin/fetch.c b/builtin/fetch.c
index d35f000..6aaf8e9 100644
--- a/builtin/fetch.c
+++ b/builtin/fetch.c
@@ -43,8 +43,7 @@ static struct option builtin_fetch_options[] = {
 		    "append to .git/FETCH_HEAD instead of overwriting"),
 	OPT_STRING(0, "upload-pack", &upload_pack, "PATH",
 		   "path to upload pack on remote end"),
-	OPT_BOOLEAN('f', "force", &force,
-		    "force overwrite of local branch"),
+	OPT__FORCE(&force, "force overwrite of local branch"),
 	OPT_BOOLEAN('m', "multiple", &multiple,
 		    "fetch from multiple remotes"),
 	OPT_SET_INT('t', "tags", &tags,
diff --git a/builtin/mv.c b/builtin/mv.c
index 8677bd2..93e8995 100644
--- a/builtin/mv.c
+++ b/builtin/mv.c
@@ -56,7 +56,7 @@ int cmd_mv(int argc, const char **argv, const char *prefix)
 	int verbose = 0, show_only = 0, force = 0, ignore_errors = 0;
 	struct option builtin_mv_options[] = {
 		OPT__DRY_RUN(&show_only, "dry run"),
-		OPT_BOOLEAN('f', "force", &force, "force move/rename even if target exists"),
+		OPT__FORCE(&force, "force move/rename even if target exists"),
 		OPT_BOOLEAN('k', NULL, &ignore_errors, "skip move/rename errors"),
 		OPT_END(),
 	};
diff --git a/builtin/notes.c b/builtin/notes.c
index 2ab070f..c85cbf5 100644
--- a/builtin/notes.c
+++ b/builtin/notes.c
@@ -538,7 +538,7 @@ static int add(int argc, const char **argv, const char *prefix)
 		{ OPTION_CALLBACK, 'C', "reuse-message", &msg, "OBJECT",
 			"reuse specified note object", PARSE_OPT_NONEG,
 			parse_reuse_arg},
-		OPT_BOOLEAN('f', "force", &force, "replace existing notes"),
+		OPT__FORCE(&force, "replace existing notes"),
 		OPT_END()
 	};
 
@@ -594,7 +594,7 @@ static int copy(int argc, const char **argv, const char *prefix)
 	struct notes_tree *t;
 	const char *rewrite_cmd = NULL;
 	struct option options[] = {
-		OPT_BOOLEAN('f', "force", &force, "replace existing notes"),
+		OPT__FORCE(&force, "replace existing notes"),
 		OPT_BOOLEAN(0, "stdin", &from_stdin, "read objects from stdin"),
 		OPT_STRING(0, "for-rewrite", &rewrite_cmd, "command",
 			   "load rewriting config for <command> (implies "
diff --git a/builtin/rm.c b/builtin/rm.c
index 49461b6..9a59905 100644
--- a/builtin/rm.c
+++ b/builtin/rm.c
@@ -142,7 +142,7 @@ static struct option builtin_rm_options[] = {
 	OPT__DRY_RUN(&show_only, "dry run"),
 	OPT__QUIET(&quiet, "be quiet"),
 	OPT_BOOLEAN( 0 , "cached",         &index_only, "only remove from the index"),
-	OPT_BOOLEAN('f', "force",          &force,      "override the up-to-date check"),
+	OPT__FORCE(&force, "override the up-to-date check"),
 	OPT_BOOLEAN('r', NULL,             &recursive,  "allow recursive removal"),
 	OPT_BOOLEAN( 0 , "ignore-unmatch", &ignore_unmatch,
 				"exit with a zero status even if nothing matched"),
diff --git a/builtin/tag.c b/builtin/tag.c
index d311491..d1d7d87 100644
--- a/builtin/tag.c
+++ b/builtin/tag.c
@@ -390,7 +390,7 @@ int cmd_tag(int argc, const char **argv, const char *prefix)
 		OPT_BOOLEAN('s', NULL, &sign, "annotated and GPG-signed tag"),
 		OPT_STRING('u', NULL, &keyid, "key-id",
 					"use another key to sign the tag"),
-		OPT_BOOLEAN('f', "force", &force, "replace the tag if exists"),
+		OPT__FORCE(&force, "replace the tag if exists"),
 
 		OPT_GROUP("Tag listing options"),
 		{
diff --git a/builtin/update-server-info.c b/builtin/update-server-info.c
index 2b3fddc..b90dce6 100644
--- a/builtin/update-server-info.c
+++ b/builtin/update-server-info.c
@@ -11,8 +11,7 @@ int cmd_update_server_info(int argc, const char **argv, const char *prefix)
 {
 	int force = 0;
 	struct option options[] = {
-		OPT_BOOLEAN('f', "force", &force,
-			"update the info files from scratch"),
+		OPT__FORCE(&force, "update the info files from scratch"),
 		OPT_END()
 	};
 
diff --git a/parse-options.h b/parse-options.h
index 3dd3a94..ae8647d 100644
--- a/parse-options.h
+++ b/parse-options.h
@@ -206,6 +206,7 @@ extern int parse_opt_tertiary(const struct option *, const char *, int);
 	{ OPTION_CALLBACK, 'q', "quiet", (var), NULL, "be more quiet", \
 	  PARSE_OPT_NOARG, &parse_opt_verbosity_cb, 0 }
 #define OPT__DRY_RUN(var, h)  OPT_BOOLEAN('n', "dry-run", (var), (h))
+#define OPT__FORCE(var, h)    OPT_BOOLEAN('f', "force",   (var), (h))
 #define OPT__ABBREV(var)  \
 	{ OPTION_CALLBACK, 0, "abbrev", (var), "n", \
 	  "use <n> digits to display SHA-1s", \
-- 
1.7.3

[PATCH 5/7] archive: improve --verbose description

[René Scharfe]

Signed-off-by: Rene Scharfe <rene.scharfe@lsrfire.ath.cx>
---
 archive.c |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/archive.c b/archive.c
index 78a67f0..1944ed4 100644
--- a/archive.c
+++ b/archive.c
@@ -314,7 +314,7 @@ static int parse_archive_args(int argc, const char **argv,
 			"write the archive to this file"),
 		OPT_BOOLEAN(0, "worktree-attributes", &worktree_attributes,
 			"read .gitattributes in working directory"),
-		OPT__VERBOSE(&verbose, "be verbose"),
+		OPT__VERBOSE(&verbose, "report archived files on stderr"),
 		OPT__COMPR('0', &compression_level, "store only", 0),
 		OPT__COMPR('1', &compression_level, "compress faster", 1),
 		OPT__COMPR_HIDDEN('2', &compression_level, 2),
-- 
1.7.3

[PATCH 6/7] branch: improve --verbose description

[René Scharfe]

Signed-off-by: Rene Scharfe <rene.scharfe@lsrfire.ath.cx>
---
 builtin/branch.c |    3 ++-
 1 files changed, 2 insertions(+), 1 deletions(-)

diff --git a/builtin/branch.c b/builtin/branch.c
index e388edc..807355a 100644
--- a/builtin/branch.c
+++ b/builtin/branch.c
@@ -621,7 +621,8 @@ int cmd_branch(int argc, const char **argv, const char *prefix)
 
 	struct option options[] = {
 		OPT_GROUP("Generic options"),
-		OPT__VERBOSE(&verbose, "be verbose"),
+		OPT__VERBOSE(&verbose,
+			"show hash and subject, give twice for upstream branch"),
 		OPT_SET_INT('t', "track",  &track, "set up tracking mode (see git-pull(1))",
 			BRANCH_TRACK_EXPLICIT),
 		OPT_SET_INT( 0, "set-upstream",  &track, "change upstream info",
-- 
1.7.3

[PATCH 7/7] verify-tag: document --verbose

[René Scharfe]

Signed-off-by: Rene Scharfe <rene.scharfe@lsrfire.ath.cx>
---
 Documentation/git-verify-tag.txt |    4 ++++
 builtin/verify-tag.c             |    2 +-
 2 files changed, 5 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-verify-tag.txt b/Documentation/git-verify-tag.txt
index dada212..7112197 100644
--- a/Documentation/git-verify-tag.txt
+++ b/Documentation/git-verify-tag.txt
@@ -15,6 +15,10 @@ Validates the gpg signature created by 'git tag'.
 
 OPTIONS
 -------
+-v::
+--verbose::
+	Print the contents of the tag object before validating it.
+
 <tag>...::
 	SHA1 identifiers of git tag objects.
 
diff --git a/builtin/verify-tag.c b/builtin/verify-tag.c
index 6784846..8136dba 100644
--- a/builtin/verify-tag.c
+++ b/builtin/verify-tag.c
@@ -93,7 +93,7 @@ int cmd_verify_tag(int argc, const char **argv, const char *prefix)
 {
 	int i = 1, verbose = 0, had_error = 0;
 	const struct option verify_tag_options[] = {
-		OPT__VERBOSE(&verbose, "be verbose"),
+		OPT__VERBOSE(&verbose, "print tag contents"),
 		OPT_END()
 	};
 
-- 
1.7.3

Re: [PATCH 3/7] add description parameter to OPT__QUIET

[René Scharfe]

And now without line wrap breakage..  Sorry.
-- >8 --
Allows better help text to be defined than "be quiet".  Also make use
of the macro in a place that already had a different description.  No
object code changes intended.

Signed-off-by: Rene Scharfe <rene.scharfe@lsrfire.ath.cx>
---
 Documentation/technical/api-parse-options.txt |    2 +-
 builtin/checkout-index.c                      |    2 +-
 builtin/checkout.c                            |    2 +-
 builtin/clean.c                               |    2 +-
 builtin/commit.c                              |    2 +-
 builtin/gc.c                                  |    2 +-
 builtin/grep.c                                |    4 ++--
 builtin/merge-file.c                          |    2 +-
 builtin/reset.c                               |    2 +-
 builtin/rm.c                                  |    2 +-
 builtin/show-ref.c                            |    2 +-
 builtin/symbolic-ref.c                        |    2 +-
 parse-options.h                               |    2 +-
 test-parse-options.c                          |    2 +-
 14 files changed, 15 insertions(+), 15 deletions(-)

diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt
index 00c447c..248a66d 100644
--- a/Documentation/technical/api-parse-options.txt
+++ b/Documentation/technical/api-parse-options.txt
@@ -121,7 +121,7 @@ There are some macros to easily define options:
 `OPT__DRY_RUN(&int_var, description)`::
 	Add `-n, \--dry-run`.
 
-`OPT__QUIET(&int_var)`::
+`OPT__QUIET(&int_var, description)`::
 	Add `-q, \--quiet`.
 
 `OPT__VERBOSE(&int_var, description)`::
diff --git a/builtin/checkout-index.c b/builtin/checkout-index.c
index 65cbee0..7ba0913 100644
--- a/builtin/checkout-index.c
+++ b/builtin/checkout-index.c
@@ -219,7 +219,7 @@ int cmd_checkout_index(int argc, const char **argv, const char *prefix)
 			"checks out all files in the index"),
 		OPT_BOOLEAN('f', "force", &force,
 			"forces overwrite of existing files"),
-		OPT__QUIET(&quiet),
+		OPT__QUIET(&quiet, "be quiet"),
 		OPT_BOOLEAN('n', "no-create", &not_new,
 			"don't checkout new files"),
 		{ OPTION_CALLBACK, 'u', "index", &newfd, NULL,
diff --git a/builtin/checkout.c b/builtin/checkout.c
index 9240faf..a952477 100644
--- a/builtin/checkout.c
+++ b/builtin/checkout.c
@@ -686,7 +686,7 @@ int cmd_checkout(int argc, const char **argv, const char *prefix)
 	int patch_mode = 0;
 	int dwim_new_local_branch = 1;
 	struct option options[] = {
-		OPT__QUIET(&opts.quiet),
+		OPT__QUIET(&opts.quiet, "be quiet"),
 		OPT_STRING('b', NULL, &opts.new_branch, "branch",
 			   "create and checkout a new branch"),
 		OPT_STRING('B', NULL, &opts.new_branch_force, "branch",
diff --git a/builtin/clean.c b/builtin/clean.c
index 17ecbe6..449d2a3 100644
--- a/builtin/clean.c
+++ b/builtin/clean.c
@@ -48,7 +48,7 @@ int cmd_clean(int argc, const char **argv, const char *prefix)
 	const char *qname;
 	char *seen = NULL;
 	struct option options[] = {
-		OPT__QUIET(&quiet),
+		OPT__QUIET(&quiet, "be quiet"),
 		OPT__DRY_RUN(&show_only, "dry run"),
 		OPT_BOOLEAN('f', "force", &force, "force"),
 		OPT_BOOLEAN('d', NULL, &remove_directories,
diff --git a/builtin/commit.c b/builtin/commit.c
index 9cbc4ea..97ae1bc 100644
--- a/builtin/commit.c
+++ b/builtin/commit.c
@@ -114,7 +114,7 @@ static int opt_parse_m(const struct option *opt, const char *arg, int unset)
 }
 
 static struct option builtin_commit_options[] = {
-	OPT__QUIET(&quiet),
+	OPT__QUIET(&quiet, "be quiet"),
 	OPT__VERBOSE(&verbose, "be verbose"),
 
 	OPT_GROUP("Commit message options"),
diff --git a/builtin/gc.c b/builtin/gc.c
index c304638..8f67325 100644
--- a/builtin/gc.c
+++ b/builtin/gc.c
@@ -180,7 +180,7 @@ int cmd_gc(int argc, const char **argv, const char *prefix)
 	char buf[80];
 
 	struct option builtin_gc_options[] = {
-		OPT__QUIET(&quiet),
+		OPT__QUIET(&quiet, "be quiet"),
 		{ OPTION_STRING, 0, "prune", &prune_expire, "date",
 			"prune unreferenced objects",
 			PARSE_OPT_OPTARG, NULL, (intptr_t)prune_expire },
diff --git a/builtin/grep.c b/builtin/grep.c
index 3d5f6ac..adb5424 100644
--- a/builtin/grep.c
+++ b/builtin/grep.c
@@ -915,8 +915,8 @@ int cmd_grep(int argc, const char **argv, const char *prefix)
 		{ OPTION_CALLBACK, ')', NULL, &opt, NULL, "",
 		  PARSE_OPT_NOARG | PARSE_OPT_NONEG | PARSE_OPT_NODASH,
 		  close_callback },
-		OPT_BOOLEAN('q', "quiet", &opt.status_only,
-			    "indicate hit with exit status without output"),
+		OPT__QUIET(&opt.status_only,
+			   "indicate hit with exit status without output"),
 		OPT_BOOLEAN(0, "all-match", &opt.all_match,
 			"show only matches from files that match all patterns"),
 		OPT_GROUP(""),
diff --git a/builtin/merge-file.c b/builtin/merge-file.c
index b6664d4..58e4731 100644
--- a/builtin/merge-file.c
+++ b/builtin/merge-file.c
@@ -39,7 +39,7 @@ int cmd_merge_file(int argc, const char **argv, const char *prefix)
 			    XDL_MERGE_FAVOR_UNION),
 		OPT_INTEGER(0, "marker-size", &xmp.marker_size,
 			    "for conflicts, use this marker size"),
-		OPT__QUIET(&quiet),
+		OPT__QUIET(&quiet, "be quiet"),
 		OPT_CALLBACK('L', NULL, names, "name",
 			     "set labels for file1/orig_file/file2", &label_cb),
 		OPT_END(),
diff --git a/builtin/reset.c b/builtin/reset.c
index 0037be4..d624207 100644
--- a/builtin/reset.c
+++ b/builtin/reset.c
@@ -243,7 +243,7 @@ int cmd_reset(int argc, const char **argv, const char *prefix)
 	struct commit *commit;
 	char *reflog_action, msg[1024];
 	const struct option options[] = {
-		OPT__QUIET(&quiet),
+		OPT__QUIET(&quiet, "be quiet"),
 		OPT_SET_INT(0, "mixed", &reset_type,
 						"reset HEAD and index", MIXED),
 		OPT_SET_INT(0, "soft", &reset_type, "reset only HEAD", SOFT),
diff --git a/builtin/rm.c b/builtin/rm.c
index 26b7412..49461b6 100644
--- a/builtin/rm.c
+++ b/builtin/rm.c
@@ -140,7 +140,7 @@ static int ignore_unmatch = 0;
 
 static struct option builtin_rm_options[] = {
 	OPT__DRY_RUN(&show_only, "dry run"),
-	OPT__QUIET(&quiet),
+	OPT__QUIET(&quiet, "be quiet"),
 	OPT_BOOLEAN( 0 , "cached",         &index_only, "only remove from the index"),
 	OPT_BOOLEAN('f', "force",          &force,      "override the up-to-date check"),
 	OPT_BOOLEAN('r', NULL,             &recursive,  "allow recursive removal"),
diff --git a/builtin/show-ref.c b/builtin/show-ref.c
index be9b512..6507f03 100644
--- a/builtin/show-ref.c
+++ b/builtin/show-ref.c
@@ -193,7 +193,7 @@ static const struct option show_ref_options[] = {
 	  "only show SHA1 hash using <n> digits",
 	  PARSE_OPT_OPTARG, &hash_callback },
 	OPT__ABBREV(&abbrev),
-	OPT__QUIET(&quiet),
+	OPT__QUIET(&quiet, "be quiet"),
 	{ OPTION_CALLBACK, 0, "exclude-existing", &exclude_existing_arg,
 	  "pattern", "show refs from stdin that aren't in local repository",
 	  PARSE_OPT_OPTARG | PARSE_OPT_NONEG, exclude_existing_callback },
diff --git a/builtin/symbolic-ref.c b/builtin/symbolic-ref.c
index ca855a5..1b28425 100644
--- a/builtin/symbolic-ref.c
+++ b/builtin/symbolic-ref.c
@@ -30,7 +30,7 @@ int cmd_symbolic_ref(int argc, const char **argv, const char *prefix)
 	int quiet = 0;
 	const char *msg = NULL;
 	struct option options[] = {
-		OPT__QUIET(&quiet),
+		OPT__QUIET(&quiet, "be quiet"),
 		OPT_STRING('m', NULL, &msg, "reason", "reason of the update"),
 		OPT_END(),
 	};
diff --git a/parse-options.h b/parse-options.h
index 69ce094..3dd3a94 100644
--- a/parse-options.h
+++ b/parse-options.h
@@ -199,7 +199,7 @@ extern int parse_opt_with_commit(const struct option *, const char *, int);
 extern int parse_opt_tertiary(const struct option *, const char *, int);
 
 #define OPT__VERBOSE(var, h)  OPT_BOOLEAN('v', "verbose", (var), (h))
-#define OPT__QUIET(var)    OPT_BOOLEAN('q', "quiet",   (var), "be quiet")
+#define OPT__QUIET(var, h)    OPT_BOOLEAN('q', "quiet",   (var), (h))
 #define OPT__VERBOSITY(var) \
 	{ OPTION_CALLBACK, 'v', "verbose", (var), NULL, "be more verbose", \
 	  PARSE_OPT_NOARG, &parse_opt_verbosity_cb, 0 }, \
diff --git a/test-parse-options.c b/test-parse-options.c
index cddd106..0828592 100644
--- a/test-parse-options.c
+++ b/test-parse-options.c
@@ -68,7 +68,7 @@ int main(int argc, const char **argv)
 		OPT__ABBREV(&abbrev),
 		OPT__VERBOSE(&verbose, "be verbose"),
 		OPT__DRY_RUN(&dry_run, "dry run"),
-		OPT__QUIET(&quiet),
+		OPT__QUIET(&quiet, "be quiet"),
 		OPT_END(),
 	};
 	int i;
-- 
1.7.3

Re: [PATCH 3/7] add description parameter to OPT__QUIET

[Jeff King]

On Mon, Nov 08, 2010 at 07:00:29PM +0100, René Scharfe wrote:

> Allows better help text to be defined than "be quiet".  Also make use
> of the macro in a place that already had a different description.  No
> object code changes intended.

Maybe my "don't repeat yourself" spider sense is over-reacting, but of
12 callsites, 11 of them will continue to use "be quiet". Maybe instead
of:

> -#define OPT__QUIET(var)    OPT_BOOLEAN('q', "quiet",   (var), "be quiet")
> +#define OPT__QUIET(var, h)    OPT_BOOLEAN('q', "quiet",   (var), (h))

we could have:

  #define OPT__QUIET_H(var, h) OPT_BOOLEAN('q', "quiet", (var), (h))
  #define OPT__QUIET(var) OPT__QUIET_H(var, "be quiet")

which would limit your patch to changing a single callsite.

-Peff

Re: [PATCH 3/7] add description parameter to OPT__QUIET

[Jonathan Nieder]

Jeff King wrote:

> Maybe my "don't repeat yourself" spider sense is over-reacting, but of
> 12 callsites, 11 of them will continue to use "be quiet".

Maybe something like this would help alleviate the smell.

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 builtin/checkout-index.c |    3 ++-
 builtin/checkout.c       |    2 +-
 builtin/clean.c          |    2 +-
 builtin/commit.c         |    4 ++--
 builtin/gc.c             |    2 +-
 builtin/merge-file.c     |    2 +-
 builtin/reset.c          |    2 +-
 builtin/rm.c             |    2 +-
 builtin/show-ref.c       |    3 ++-
 builtin/symbolic-ref.c   |    3 ++-
 10 files changed, 14 insertions(+), 11 deletions(-)

diff --git a/builtin/checkout-index.c b/builtin/checkout-index.c
index 91fb9bf..1ee3044 100644
--- a/builtin/checkout-index.c
+++ b/builtin/checkout-index.c
@@ -218,7 +218,8 @@ int cmd_checkout_index(int argc, const char **argv, const char *prefix)
 		OPT_BOOLEAN('a', "all", &all,
 			"checks out all files in the index"),
 		OPT__FORCE(&force, "forces overwrite of existing files"),
-		OPT__QUIET(&quiet, "be quiet"),
+		OPT__QUIET(&quiet,
+			"no warning for existing files and files not in index"),
 		OPT_BOOLEAN('n', "no-create", &not_new,
 			"don't checkout new files"),
 		{ OPTION_CALLBACK, 'u', "index", &newfd, NULL,
diff --git a/builtin/checkout.c b/builtin/checkout.c
index ab935fd..07530d7 100644
--- a/builtin/checkout.c
+++ b/builtin/checkout.c
@@ -686,7 +686,7 @@ int cmd_checkout(int argc, const char **argv, const char *prefix)
 	int patch_mode = 0;
 	int dwim_new_local_branch = 1;
 	struct option options[] = {
-		OPT__QUIET(&opts.quiet, "be quiet"),
+		OPT__QUIET(&opts.quiet, "suppress progress reporting"),
 		OPT_STRING('b', NULL, &opts.new_branch, "branch",
 			   "create and checkout a new branch"),
 		OPT_STRING('B', NULL, &opts.new_branch_force, "branch",
diff --git a/builtin/clean.c b/builtin/clean.c
index 9146bf3..5e47c53 100644
--- a/builtin/clean.c
+++ b/builtin/clean.c
@@ -48,7 +48,7 @@ int cmd_clean(int argc, const char **argv, const char *prefix)
 	const char *qname;
 	char *seen = NULL;
 	struct option options[] = {
-		OPT__QUIET(&quiet, "be quiet"),
+		OPT__QUIET(&quiet, "do not print names of files removed"),
 		OPT__DRY_RUN(&show_only, "dry run"),
 		OPT__FORCE(&force, "force"),
 		OPT_BOOLEAN('d', NULL, &remove_directories,
diff --git a/builtin/commit.c b/builtin/commit.c
index 97ae1bc..4fd1a16 100644
--- a/builtin/commit.c
+++ b/builtin/commit.c
@@ -114,8 +114,8 @@ static int opt_parse_m(const struct option *opt, const char *arg, int unset)
 }
 
 static struct option builtin_commit_options[] = {
-	OPT__QUIET(&quiet, "be quiet"),
-	OPT__VERBOSE(&verbose, "be verbose"),
+	OPT__QUIET(&quiet, "suppress summary after successful commit"),
+	OPT__VERBOSE(&verbose, "show diff in commit message template"),
 
 	OPT_GROUP("Commit message options"),
 	OPT_FILENAME('F', "file", &logfile, "read log from file"),
diff --git a/builtin/gc.c b/builtin/gc.c
index 8f67325..397a1e6 100644
--- a/builtin/gc.c
+++ b/builtin/gc.c
@@ -180,7 +180,7 @@ int cmd_gc(int argc, const char **argv, const char *prefix)
 	char buf[80];
 
 	struct option builtin_gc_options[] = {
-		OPT__QUIET(&quiet, "be quiet"),
+		OPT__QUIET(&quiet, "suppress progress reporting"),
 		{ OPTION_STRING, 0, "prune", &prune_expire, "date",
 			"prune unreferenced objects",
 			PARSE_OPT_OPTARG, NULL, (intptr_t)prune_expire },
diff --git a/builtin/merge-file.c b/builtin/merge-file.c
index 58e4731..9d75ed4 100644
--- a/builtin/merge-file.c
+++ b/builtin/merge-file.c
@@ -39,7 +39,7 @@ int cmd_merge_file(int argc, const char **argv, const char *prefix)
 			    XDL_MERGE_FAVOR_UNION),
 		OPT_INTEGER(0, "marker-size", &xmp.marker_size,
 			    "for conflicts, use this marker size"),
-		OPT__QUIET(&quiet, "be quiet"),
+		OPT__QUIET(&quiet, "do not warn about conflicts"),
 		OPT_CALLBACK('L', NULL, names, "name",
 			     "set labels for file1/orig_file/file2", &label_cb),
 		OPT_END(),
diff --git a/builtin/reset.c b/builtin/reset.c
index d624207..5de2bce 100644
--- a/builtin/reset.c
+++ b/builtin/reset.c
@@ -243,7 +243,7 @@ int cmd_reset(int argc, const char **argv, const char *prefix)
 	struct commit *commit;
 	char *reflog_action, msg[1024];
 	const struct option options[] = {
-		OPT__QUIET(&quiet, "be quiet"),
+		OPT__QUIET(&quiet, "be quiet, only report errors"),
 		OPT_SET_INT(0, "mixed", &reset_type,
 						"reset HEAD and index", MIXED),
 		OPT_SET_INT(0, "soft", &reset_type, "reset only HEAD", SOFT),
diff --git a/builtin/rm.c b/builtin/rm.c
index 9a59905..c7b7bb3 100644
--- a/builtin/rm.c
+++ b/builtin/rm.c
@@ -140,7 +140,7 @@ static int ignore_unmatch = 0;
 
 static struct option builtin_rm_options[] = {
 	OPT__DRY_RUN(&show_only, "dry run"),
-	OPT__QUIET(&quiet, "be quiet"),
+	OPT__QUIET(&quiet, "do not list removed files"),
 	OPT_BOOLEAN( 0 , "cached",         &index_only, "only remove from the index"),
 	OPT__FORCE(&force, "override the up-to-date check"),
 	OPT_BOOLEAN('r', NULL,             &recursive,  "allow recursive removal"),
diff --git a/builtin/show-ref.c b/builtin/show-ref.c
index 6507f03..45f0340 100644
--- a/builtin/show-ref.c
+++ b/builtin/show-ref.c
@@ -193,7 +193,8 @@ static const struct option show_ref_options[] = {
 	  "only show SHA1 hash using <n> digits",
 	  PARSE_OPT_OPTARG, &hash_callback },
 	OPT__ABBREV(&abbrev),
-	OPT__QUIET(&quiet, "be quiet"),
+	OPT__QUIET(&quiet,
+		   "do not print results to stdout (useful with --verify)"),
 	{ OPTION_CALLBACK, 0, "exclude-existing", &exclude_existing_arg,
 	  "pattern", "show refs from stdin that aren't in local repository",
 	  PARSE_OPT_OPTARG | PARSE_OPT_NONEG, exclude_existing_callback },
diff --git a/builtin/symbolic-ref.c b/builtin/symbolic-ref.c
index 1b28425..dea849c 100644
--- a/builtin/symbolic-ref.c
+++ b/builtin/symbolic-ref.c
@@ -30,7 +30,8 @@ int cmd_symbolic_ref(int argc, const char **argv, const char *prefix)
 	int quiet = 0;
 	const char *msg = NULL;
 	struct option options[] = {
-		OPT__QUIET(&quiet, "be quiet"),
+		OPT__QUIET(&quiet,
+			"suppress error message for non-symbolic (detached) refs"),
 		OPT_STRING('m', NULL, &msg, "reason", "reason of the update"),
 		OPT_END(),
 	};
-- 
1.7.2.3.557.gab647.dirty

Re: [PATCH 3/7] add description parameter to OPT__QUIET

[Jeff King]

On Mon, Nov 08, 2010 at 01:54:48PM -0600, Jonathan Nieder wrote:

> Jeff King wrote:
> 
> > Maybe my "don't repeat yourself" spider sense is over-reacting, but of
> > 12 callsites, 11 of them will continue to use "be quiet".
> 
> Maybe something like this would help alleviate the smell.
> [patch with actual per-command descriptions of quiet mode]

Yeah, that is even better.

-Peff

Re: [PATCH 3/7] add description parameter to OPT__QUIET

[René Scharfe]

Am 08.11.2010 20:54, schrieb Jonathan Nieder:
> Jeff King wrote:
> 
>> Maybe my "don't repeat yourself" spider sense is over-reacting, but of
>> 12 callsites, 11 of them will continue to use "be quiet".
> 
> Maybe something like this would help alleviate the smell.

Yes, patches like yours were what I was hoping for. :)

Thanks,
René