Merge branch 'rs/opt-help-text'

* rs/opt-help-text:
  verify-tag: document --verbose
  branch: improve --verbose description
  archive: improve --verbose description
  Describe various forms of "be quiet" using OPT__QUIET
  add OPT__FORCE
  add description parameter to OPT__QUIET
  add description parameter to OPT__DRY_RUN
  add description parameter to OPT__VERBOSE

26 files changed, 48 insertions, 49 deletions

diff --git a/builtin/add.c b/builtin/add.c
index 56a4e0af6..71f9b04fe 100644
--- a/builtin/add.c
+++ b/builtin/add.c
@@ -313,13 +313,13 @@ 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__VERBOSE(&verbose),
+	OPT__DRY_RUN(&show_only, "dry run"),
+	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('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/apply.c b/builtin/apply.c
index f051e66dc..96246e960 100644
--- a/builtin/apply.c
+++ b/builtin/apply.c
@@ -3849,7 +3849,7 @@ int cmd_apply(int argc, const char **argv, const char *prefix_)
 			"don't expect at least one line of context"),
 		OPT_BOOLEAN(0, "reject", &apply_with_reject,
 			"leave the rejected hunks in corresponding *.rej files"),
-		OPT__VERBOSE(&apply_verbosely),
+		OPT__VERBOSE(&apply_verbosely, "be verbose"),
 		OPT_BIT(0, "inaccurate-eof", &options,
 			"tolerate incorrectly detected missing new-line at the end of file",
 			INACCURATE_EOF),
diff --git a/builtin/branch.c b/builtin/branch.c
index 87976f092..807355a19 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),
+		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",
@@ -651,7 +652,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 65cbee055..1ee304430 100644
--- a/builtin/checkout-index.c
+++ b/builtin/checkout-index.c
@@ -217,9 +217,9 @@ 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__QUIET(&quiet),
+		OPT__FORCE(&force, "forces overwrite of existing files"),
+		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 1fa9ce43f..757f9a08d 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, "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",
@@ -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 fb2403075..4a312abc6 100644
--- a/builtin/clean.c
+++ b/builtin/clean.c
@@ -48,9 +48,9 @@ int cmd_clean(int argc, const char **argv, const char *prefix)
 	const char *qname;
 	char *seen = NULL;
 	struct option options[] = {
-		OPT__QUIET(&quiet),
-		OPT__DRY_RUN(&show_only),
-		OPT_BOOLEAN('f', "force", &force, "force"),
+		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,
 				"remove whole directories"),
 		{ OPTION_CALLBACK, 'e', "exclude", &exclude_list, "pattern",
diff --git a/builtin/commit.c b/builtin/commit.c
index 66fdd2202..4fd1a1692 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),
-	OPT__VERBOSE(&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"),
@@ -1048,7 +1048,7 @@ int cmd_status(int argc, const char **argv, const char *prefix)
 	int fd;
 	unsigned char sha1[20];
 	static struct option builtin_status_options[] = {
-		OPT__VERBOSE(&verbose),
+		OPT__VERBOSE(&verbose, "be verbose"),
 		OPT_SET_INT('s', "short", &status_format,
 			    "show status concisely", STATUS_FORMAT_SHORT),
 		OPT_BOOLEAN('b', "branch", &status_show_branch,
diff --git a/builtin/count-objects.c b/builtin/count-objects.c
index 2bdd8ebde..c37cb98c3 100644
--- a/builtin/count-objects.c
+++ b/builtin/count-objects.c
@@ -79,7 +79,7 @@ int cmd_count_objects(int argc, const char **argv, const char *prefix)
 	unsigned long loose = 0, packed = 0, packed_loose = 0, garbage = 0;
 	off_t loose_size = 0;
 	struct option opts[] = {
-		OPT__VERBOSE(&verbose),
+		OPT__VERBOSE(&verbose, "be verbose"),
 		OPT_END(),
 	};
 
diff --git a/builtin/fetch.c b/builtin/fetch.c
index 4243ef022..6bcce55c0 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/fsck.c b/builtin/fsck.c
index 0929c7f24..6d5ebca7a 100644
--- a/builtin/fsck.c
+++ b/builtin/fsck.c
@@ -572,7 +572,7 @@ static char const * const fsck_usage[] = {
 };
 
 static struct option fsck_opts[] = {
-	OPT__VERBOSE(&verbose),
+	OPT__VERBOSE(&verbose, "be verbose"),
 	OPT_BOOLEAN(0, "unreachable", &show_unreachable, "show unreachable objects"),
 	OPT_BOOLEAN(0, "tags", &show_tags, "report tags"),
 	OPT_BOOLEAN(0, "root", &show_root, "report root nodes"),
diff --git a/builtin/gc.c b/builtin/gc.c
index c304638b7..397a1e6eb 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, "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/grep.c b/builtin/grep.c
index 3d5f6ace9..adb542494 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/log.c b/builtin/log.c
index 22d12903a..d0297a1c5 100644
--- a/builtin/log.c
+++ b/builtin/log.c
@@ -1365,7 +1365,7 @@ int cmd_cherry(int argc, const char **argv, const char *prefix)
 
 	struct option options[] = {
 		OPT__ABBREV(&abbrev),
-		OPT__VERBOSE(&verbose),
+		OPT__VERBOSE(&verbose, "be verbose"),
 		OPT_END()
 	};
 
diff --git a/builtin/merge-file.c b/builtin/merge-file.c
index 6c4afb5a3..237abd3c0 100644
--- a/builtin/merge-file.c
+++ b/builtin/merge-file.c
@@ -40,7 +40,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, "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/mv.c b/builtin/mv.c
index cdbb09473..93e8995d9 100644
--- a/builtin/mv.c
+++ b/builtin/mv.c
@@ -55,8 +55,8 @@ 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_BOOLEAN('f', "force", &force, "force move/rename even if target exists"),
+		OPT__DRY_RUN(&show_only, "dry run"),
+		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 6d07aac80..c85cbf5a4 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 "
@@ -804,9 +804,8 @@ 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_BOOLEAN('v', "verbose", &verbose, "report pruned notes"),
+		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 99218ba49..e65690ba3 100644
--- a/builtin/prune.c
+++ b/builtin/prune.c
@@ -125,9 +125,8 @@ 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_BOOLEAN('v', "verbose", &verbose, "report pruned objects"),
+		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>"),
 		OPT_END()
diff --git a/builtin/read-tree.c b/builtin/read-tree.c
index eb1e3e746..73c89ed15 100644
--- a/builtin/read-tree.c
+++ b/builtin/read-tree.c
@@ -109,7 +109,7 @@ int cmd_read_tree(int argc, const char **argv, const char *unused_prefix)
 		  PARSE_OPT_NONEG, index_output_cb },
 		OPT_SET_INT(0, "empty", &read_empty,
 			    "only empty the index", 1),
-		OPT__VERBOSE(&opts.verbose_update),
+		OPT__VERBOSE(&opts.verbose_update, "be verbose"),
 		OPT_GROUP("Merging"),
 		OPT_SET_INT('m', NULL, &opts.merge,
 			    "perform a merge in addition to a read", 1),
diff --git a/builtin/remote.c b/builtin/remote.c
index 6a0628219..cb2608095 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()
 	};
 
@@ -1512,7 +1512,7 @@ static int show_all(void)
 int cmd_remote(int argc, const char **argv, const char *prefix)
 {
 	struct option options[] = {
-		OPT_BOOLEAN('v', "verbose", &verbose, "be verbose; must be placed before a subcommand"),
+		OPT__VERBOSE(&verbose, "be verbose; must be placed before a subcommand"),
 		OPT_END()
 	};
 	int result;
diff --git a/builtin/reset.c b/builtin/reset.c
index 0037be469..5de2bceee 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, 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 f3772c84d..c7b7bb37a 100644
--- a/builtin/rm.c
+++ b/builtin/rm.c
@@ -139,10 +139,10 @@ 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__QUIET(&quiet),
+	OPT__DRY_RUN(&show_only, "dry run"),
+	OPT__QUIET(&quiet, "do not list removed files"),
 	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/show-ref.c b/builtin/show-ref.c
index be9b512ee..45f0340c3 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),
+	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 ca855a5eb..dea849c3c 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),
+		OPT__QUIET(&quiet,
+			"suppress error message for non-symbolic (detached) refs"),
 		OPT_STRING('m', NULL, &msg, "reason", "reason of the update"),
 		OPT_END(),
 	};
diff --git a/builtin/tag.c b/builtin/tag.c
index d311491e4..d1d7d8701 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 2b3fddcc6..b90dce635 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/builtin/verify-tag.c b/builtin/verify-tag.c
index 9f482c29f..8136dba7a 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),
+		OPT__VERBOSE(&verbose, "print tag contents"),
 		OPT_END()
 	};