[PATCH/RFC] parse-options: allow to define hidden synonym options

[PATCH/RFC] parse-options: allow to define hidden synonym options

[Junio C Hamano]

By setting the help member to NULL, you can implement an option
that is not shown in the "git-cmd -h" help output.  This is
useful to support backward compatible synonyms without
cluttering the help text.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 parse-options.c |    2 ++
 parse-options.h |    2 +-
 2 files changed, 3 insertions(+), 1 deletions(-)

diff --git a/parse-options.c b/parse-options.c
index d3e608a..1ee2c81 100644
--- a/parse-options.c
+++ b/parse-options.c
@@ -284,6 +284,8 @@ void usage_with_options(const char * const *usagestr,
 			if (*opts->help)
 				fprintf(stderr, "%s\n", opts->help);
 			continue;
+		} else if (!opts->help) {
+			continue;
 		}
 
 		pos = fprintf(stderr, "    ");
diff --git a/parse-options.h b/parse-options.h
index a8760ac..de249a0 100644
--- a/parse-options.h
+++ b/parse-options.h
@@ -49,7 +49,7 @@ typedef int parse_opt_cb(const struct option *, const char *arg, int unset);
  *
  * `help`::
  *   the short help associated to what the option does.
- *   Must never be NULL (except for OPTION_END).
+ *   option with this field set to NULL does not appear in the help listing.
  *   OPTION_GROUP uses this pointer to store the group header.
  *
  * `flags`::
-- 
1.5.3.6.1779.ga3ed

[PATCH Illustration] branch --contains=<commit>

[Junio C Hamano]

This renames the --with=<commit> option to --contains=<commit>, but still
supports the earlier --with=<commit> variant as a hidden synonym.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---

 * An example usage of the ".help = NULL" member in the options
   structure.

 builtin-branch.c |    5 ++++-
 1 files changed, 4 insertions(+), 1 deletions(-)

diff --git a/builtin-branch.c b/builtin-branch.c
index fd36e4f..5dc0c57 100644
--- a/builtin-branch.c
+++ b/builtin-branch.c
@@ -562,9 +562,12 @@ int cmd_branch(int argc, const char **argv, const char *prefix)
 		OPT_BOOLEAN( 0 , "color",  &branch_use_color, "use colored output"),
 		OPT_SET_INT('r', NULL,     &kinds, "act on remote-tracking branches",
 			REF_REMOTE_BRANCH),
-		OPT_CALLBACK(0, "with",    &with_commit, "commit",
+		OPT_CALLBACK(0, "contains",&with_commit, "commit",
 			     "print only branches that contain the commit",
 			     opt_parse_with_commit),
+		OPT_CALLBACK(0, "with",    &with_commit, "commit",
+			     NULL,
+			     opt_parse_with_commit),
 		OPT__ABBREV(&abbrev),
 
 		OPT_GROUP("Specific git-branch actions:"),
-- 
1.5.3.6.1788.gcc5c4

Re: [PATCH/RFC] parse-options: allow to define hidden synonym options

[Pierre Habouzit]

[-- Attachment #1: Type: text/plain, Size: 4852 bytes --]

On lun, nov 19, 2007 at 06:09:41 +0000, Junio C Hamano wrote:
> By setting the help member to NULL, you can implement an option
> that is not shown in the "git-cmd -h" help output.  This is
> useful to support backward compatible synonyms without
> cluttering the help text.

  Sorry I'm not very present those days, but oh well...

  The idea looks nice, though if we are doing this, I'd like to see it
fix other problems at the same time. We sometimes have "internal"
commands switches and other cases of alias.

  I wonder if it wouldn't be better that we have some kind of --help-all
switch that would show them _all_ and a way (through another flag ?) to
hide those additional options by default.

  And defining an alias would then be:

  { OPTION_SOME_TYPE, 0, "alias-name", &some_value, "some-arg",
    "backward compatibility alias for \"foo\"", PARSE_OPT_HIDE, ... }

or:

  { OPTION_SOME_TYPE, 0, "plumbing-dark-think", &some_value, "some-arg",
    "internal plumbing switch used in", PARSE_OPT_HIDE, ... }


  I personnaly don't like that parse-opt sees more options than what it
says it sees, else with your patch, if the user gives ambiguous
abbreviated long switches, he'll get "--w is ambiguous, could be
`--whith` or `--wibble`" whereas he never knew that --with existed in
the first place.

  That gives something more along the lines of :

From 860a5bf335e44dd2bbe5f30620c99d174b697f69 Mon Sep 17 00:00:00 2001
From: Pierre Habouzit <madcoder@debian.org>
Date: Mon, 19 Nov 2007 10:21:44 +0100
Subject: [PATCH] parse-options: Allow to hide options from the default usage.

This is useful for backward-compatibility aliases, or very advanced command
line switches introduced for internal git usages and have no real use for a
user.

parse-options still shows them if the user asks for --help-all.

Signed-off-by: Pierre Habouzit <madcoder@debian.org>
---
 parse-options.c |   17 +++++++++++++++--
 parse-options.h |    3 +++
 2 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/parse-options.c b/parse-options.c
index d3e608a..807e443 100644
--- a/parse-options.c
+++ b/parse-options.c
@@ -216,6 +216,9 @@ is_abbreviated:
 	return error("unknown option `%s'", arg);
 }
 
+static NORETURN void usage_with_options_internal(const char * const *,
+                                                 const struct option *, int);
+
 int parse_options(int argc, const char **argv, const struct option *options,
                   const char * const usagestr[], int flags)
 {
@@ -249,6 +252,8 @@ int parse_options(int argc, const char **argv, const struct option *options,
 			break;
 		}
 
+		if (!strcmp(arg + 2, "help-all"))
+			usage_with_options_internal(usagestr, options, 1);
 		if (!strcmp(arg + 2, "help"))
 			usage_with_options(usagestr, options);
 		if (parse_long_opt(&args, arg + 2, options))
@@ -263,8 +268,8 @@ int parse_options(int argc, const char **argv, const struct option *options,
 #define USAGE_OPTS_WIDTH 24
 #define USAGE_GAP         2
 
-void usage_with_options(const char * const *usagestr,
-                        const struct option *opts)
+void usage_with_options_internal(const char * const *usagestr,
+                                 const struct option *opts, int full)
 {
 	fprintf(stderr, "usage: %s\n", *usagestr++);
 	while (*usagestr && **usagestr)
@@ -285,6 +290,8 @@ void usage_with_options(const char * const *usagestr,
 				fprintf(stderr, "%s\n", opts->help);
 			continue;
 		}
+		if (!full & (opts->flags & PARSE_OPT_HIDDEN))
+			continue;
 
 		pos = fprintf(stderr, "    ");
 		if (opts->short_name)
@@ -335,6 +342,12 @@ void usage_with_options(const char * const *usagestr,
 	exit(129);
 }
 
+void usage_with_options(const char * const *usagestr,
+                        const struct option *opts)
+{
+	usage_with_options_internal(usagestr, opts, 0);
+}
+
 /*----- some often used options -----*/
 #include "cache.h"
 
diff --git a/parse-options.h b/parse-options.h
index a8760ac..102ac31 100644
--- a/parse-options.h
+++ b/parse-options.h
@@ -24,6 +24,7 @@ enum parse_opt_option_flags {
 	PARSE_OPT_OPTARG  = 1,
 	PARSE_OPT_NOARG   = 2,
 	PARSE_OPT_NONEG   = 4,
+	PARSE_OPT_HIDDEN  = 8,
 };
 
 struct option;
@@ -57,6 +58,8 @@ typedef int parse_opt_cb(const struct option *, const char *arg, int unset);
  *   PARSE_OPT_OPTARG: says that the argument is optionnal (not for BOOLEANs)
  *   PARSE_OPT_NOARG: says that this option takes no argument, for CALLBACKs
  *   PARSE_OPT_NONEG: says that this option cannot be negated
+ *   PARSE_OPT_HIDDEN this option is skipped in the default usage, showed in
+ *                    the long one.
  *
  * `callback`::
  *   pointer to the callback to use for OPTION_CALLBACK.
-- 
1.5.3.5.1795.g5421e-dirty


[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]