Documentation/technical/api-parse-options.txt

   1 parse-options API
   2 =================
   3
   4 The parse-options API is used to parse and massage options in Git
   5 and to provide a usage help with consistent look.
   6
   7 Basics
   8 ------
   9
  10 The argument vector `argv[]` may usually contain mandatory or optional
  11 'non-option arguments', e.g. a filename or a branch, and 'options'.
  12 Options are optional arguments that start with a dash and
  13 that allow to change the behavior of a command.
  14
  15 * There are basically three types of options:
  16   'boolean' options,
  17   options with (mandatory) 'arguments' and
  18   options with 'optional arguments'
  19   (i.e. a boolean option that can be adjusted).
  20
  21 * There are basically two forms of options:
  22   'Short options' consist of one dash (`-`) and one alphanumeric
  23   character.
  24   'Long options' begin with two dashes (`--`) and some
  25   alphanumeric characters.
  26
  27 * Options are case-sensitive.
  28   Please define 'lower-case long options' only.
  29
  30 The parse-options API allows:
  31
  32 * 'stuck' and 'separate form' of options with arguments.
  33   `-oArg` is stuck, `-o Arg` is separate form.
  34   `--option=Arg` is stuck, `--option Arg` is separate form.
  35
  36 * Long options may be 'abbreviated', as long as the abbreviation
  37   is unambiguous.
  38
  39 * Short options may be bundled, e.g. `-a -b` can be specified as `-ab`.
  40
  41 * Boolean long options can be 'negated' (or 'unset') by prepending
  42   `no-`, e.g. `--no-abbrev` instead of `--abbrev`. Conversely,
  43   options that begin with `no-` can be 'negated' by removing it.
  44   Other long options can be unset (e.g., set string to NULL, set
  45   integer to 0) by prepending `no-`.
  46
  47 * Options and non-option arguments can clearly be separated using the `--`
  48   option, e.g. `-a -b --option -- --this-is-a-file` indicates that
  49   `--this-is-a-file` must not be processed as an option.
  50
  51 Steps to parse options
  52 ----------------------
  53
  54 . `#include "parse-options.h"`
  55
  56 . define a NULL-terminated
  57   `static const char * const builtin_foo_usage[]` array
  58   containing alternative usage strings
  59
  60 . define `builtin_foo_options` array as described below
  61   in section 'Data Structure'.
  62
  63 . in `cmd_foo(int argc, const char **argv, const char *prefix)`
  64   call
  65
  66         argc = parse_options(argc, argv, prefix, builtin_foo_options, builtin_foo_usage, flags);
  67 +
  68 `parse_options()` will filter out the processed options of `argv[]` and leave the
  69 non-option arguments in `argv[]`.
  70 `argc` is updated appropriately because of the assignment.
  71 +
  72 You can also pass NULL instead of a usage array as the fifth parameter of
  73 parse_options(), to avoid displaying a help screen with usage info and
  74 option list.  This should only be done if necessary, e.g. to implement
  75 a limited parser for only a subset of the options that needs to be run
  76 before the full parser, which in turn shows the full help message.
  77 +
  78 Flags are the bitwise-or of:
  79
  80 `PARSE_OPT_KEEP_DASHDASH`::
  81         Keep the `--` that usually separates options from
  82         non-option arguments.
  83
  84 `PARSE_OPT_STOP_AT_NON_OPTION`::
  85         Usually the whole argument vector is massaged and reordered.
  86         Using this flag, processing is stopped at the first non-option
  87         argument.
  88
  89 `PARSE_OPT_KEEP_ARGV0`::
  90         Keep the first argument, which contains the program name.  It's
  91         removed from argv[] by default.
  92
  93 `PARSE_OPT_KEEP_UNKNOWN`::
  94         Keep unknown arguments instead of erroring out.  This doesn't
  95         work for all combinations of arguments as users might expect
  96         it to do.  E.g. if the first argument in `--unknown --known`
  97         takes a value (which we can't know), the second one is
  98         mistakenly interpreted as a known option.  Similarly, if
  99         `PARSE_OPT_STOP_AT_NON_OPTION` is set, the second argument in
 100         `--unknown value` will be mistakenly interpreted as a
 101         non-option, not as a value belonging to the unknown option,
 102         the parser early.  That's why parse_options() errors out if
 103         both options are set.
 104
 105 `PARSE_OPT_NO_INTERNAL_HELP`::
 106         By default, parse_options() handles `-h`, `--help` and
 107         `--help-all` internally, by showing a help screen.  This option
 108         turns it off and allows one to add custom handlers for these
 109         options, or to just leave them unknown.
 110
 111 Data Structure
 112 --------------
 113
 114 The main data structure is an array of the `option` struct,
 115 say `static struct option builtin_add_options[]`.
 116 There are some macros to easily define options:
 117
 118 `OPT__ABBREV(&int_var)`::
 119         Add `--abbrev[=<n>]`.
 120
 121 `OPT__COLOR(&int_var, description)`::
 122         Add `--color[=<when>]` and `--no-color`.
 123
 124 `OPT__DRY_RUN(&int_var, description)`::
 125         Add `-n, --dry-run`.
 126
 127 `OPT__FORCE(&int_var, description)`::
 128         Add `-f, --force`.
 129
 130 `OPT__QUIET(&int_var, description)`::
 131         Add `-q, --quiet`.
 132
 133 `OPT__VERBOSE(&int_var, description)`::
 134         Add `-v, --verbose`.
 135
 136 `OPT_GROUP(description)`::
 137         Start an option group. `description` is a short string that
 138         describes the group or an empty string.
 139         Start the description with an upper-case letter.
 140
 141 `OPT_BOOL(short, long, &int_var, description)`::
 142         Introduce a boolean option. `int_var` is set to one with
 143         `--option` and set to zero with `--no-option`.
 144
 145 `OPT_COUNTUP(short, long, &int_var, description)`::
 146         Introduce a count-up option.
 147         `int_var` is incremented on each use of `--option`, and
 148         reset to zero with `--no-option`.
 149
 150 `OPT_BIT(short, long, &int_var, description, mask)`::
 151         Introduce a boolean option.
 152         If used, `int_var` is bitwise-ored with `mask`.
 153
 154 `OPT_NEGBIT(short, long, &int_var, description, mask)`::
 155         Introduce a boolean option.
 156         If used, `int_var` is bitwise-anded with the inverted `mask`.
 157
 158 `OPT_SET_INT(short, long, &int_var, description, integer)`::
 159         Introduce an integer option.
 160         `int_var` is set to `integer` with `--option`, and
 161         reset to zero with `--no-option`.
 162
 163 `OPT_STRING(short, long, &str_var, arg_str, description)`::
 164         Introduce an option with string argument.
 165         The string argument is put into `str_var`.
 166
 167 `OPT_INTEGER(short, long, &int_var, description)`::
 168         Introduce an option with integer argument.
 169         The integer is put into `int_var`.
 170
 171 `OPT_MAGNITUDE(short, long, &unsigned_long_var, description)`::
 172         Introduce an option with a size argument. The argument must be a
 173         non-negative integer and may include a suffix of 'k', 'm' or 'g' to
 174         scale the provided value by 1024, 1024^2 or 1024^3 respectively.
 175         The scaled value is put into `unsigned_long_var`.
 176
 177 `OPT_DATE(short, long, &int_var, description)`::
 178         Introduce an option with date argument, see `approxidate()`.
 179         The timestamp is put into `int_var`.
 180
 181 `OPT_EXPIRY_DATE(short, long, &int_var, description)`::
 182         Introduce an option with expiry date argument, see `parse_expiry_date()`.
 183         The timestamp is put into `int_var`.
 184
 185 `OPT_CALLBACK(short, long, &var, arg_str, description, func_ptr)`::
 186         Introduce an option with argument.
 187         The argument will be fed into the function given by `func_ptr`
 188         and the result will be put into `var`.
 189         See 'Option Callbacks' below for a more elaborate description.
 190
 191 `OPT_FILENAME(short, long, &var, description)`::
 192         Introduce an option with a filename argument.
 193         The filename will be prefixed by passing the filename along with
 194         the prefix argument of `parse_options()` to `prefix_filename()`.
 195
 196 `OPT_ARGUMENT(long, description)`::
 197         Introduce a long-option argument that will be kept in `argv[]`.
 198
 199 `OPT_NUMBER_CALLBACK(&var, description, func_ptr)`::
 200         Recognize numerical options like -123 and feed the integer as
 201         if it was an argument to the function given by `func_ptr`.
 202         The result will be put into `var`.  There can be only one such
 203         option definition.  It cannot be negated and it takes no
 204         arguments.  Short options that happen to be digits take
 205         precedence over it.
 206
 207 `OPT_COLOR_FLAG(short, long, &int_var, description)`::
 208         Introduce an option that takes an optional argument that can
 209         have one of three values: "always", "never", or "auto".  If the
 210         argument is not given, it defaults to "always".  The `--no-` form
 211         works like `--long=never`; it cannot take an argument.  If
 212         "always", set `int_var` to 1; if "never", set `int_var` to 0; if
 213         "auto", set `int_var` to 1 if stdout is a tty or a pager,
 214         0 otherwise.
 215
 216 `OPT_NOOP_NOARG(short, long)`::
 217         Introduce an option that has no effect and takes no arguments.
 218         Use it to hide deprecated options that are still to be recognized
 219         and ignored silently.
 220
 221 `OPT_PASSTHRU(short, long, &char_var, arg_str, description, flags)`::
 222         Introduce an option that will be reconstructed into a char* string,
 223         which must be initialized to NULL. This is useful when you need to
 224         pass the command-line option to another command. Any previous value
 225         will be overwritten, so this should only be used for options where
 226         the last one specified on the command line wins.
 227
 228 `OPT_PASSTHRU_ARGV(short, long, &argv_array_var, arg_str, description, flags)`::
 229         Introduce an option where all instances of it on the command-line will
 230         be reconstructed into an argv_array. This is useful when you need to
 231         pass the command-line option, which can be specified multiple times,
 232         to another command.
 233
 234 `OPT_CMDMODE(short, long, &int_var, description, enum_val)`::
 235         Define an "operation mode" option, only one of which in the same
 236         group of "operating mode" options that share the same `int_var`
 237         can be given by the user. `enum_val` is set to `int_var` when the
 238         option is used, but an error is reported if other "operating mode"
 239         option has already set its value to the same `int_var`.
 240
 241
 242 The last element of the array must be `OPT_END()`.
 243
 244 If not stated otherwise, interpret the arguments as follows:
 245
 246 * `short` is a character for the short option
 247   (e.g. `'e'` for `-e`, use `0` to omit),
 248
 249 * `long` is a string for the long option
 250   (e.g. `"example"` for `--example`, use `NULL` to omit),
 251
 252 * `int_var` is an integer variable,
 253
 254 * `str_var` is a string variable (`char *`),
 255
 256 * `arg_str` is the string that is shown as argument
 257   (e.g. `"branch"` will result in `<branch>`).
 258   If set to `NULL`, three dots (`...`) will be displayed.
 259
 260 * `description` is a short string to describe the effect of the option.
 261   It shall begin with a lower-case letter and a full stop (`.`) shall be
 262   omitted at the end.
 263
 264 Option Callbacks
 265 ----------------
 266
 267 The function must be defined in this form:
 268
 269         int func(const struct option *opt, const char *arg, int unset)
 270
 271 The callback mechanism is as follows:
 272
 273 * Inside `func`, the only interesting member of the structure
 274   given by `opt` is the void pointer `opt->value`.
 275   `*opt->value` will be the value that is saved into `var`, if you
 276   use `OPT_CALLBACK()`.
 277   For example, do `*(unsigned long *)opt->value = 42;` to get 42
 278   into an `unsigned long` variable.
 279
 280 * Return value `0` indicates success and non-zero return
 281   value will invoke `usage_with_options()` and, thus, die.
 282
 283 * If the user negates the option, `arg` is `NULL` and `unset` is 1.
 284
 285 Sophisticated option parsing
 286 ----------------------------
 287
 288 If you need, for example, option callbacks with optional arguments
 289 or without arguments at all, or if you need other special cases,
 290 that are not handled by the macros above, you need to specify the
 291 members of the `option` structure manually.
 292
 293 This is not covered in this document, but well documented
 294 in `parse-options.h` itself.
 295
 296 Examples
 297 --------
 298
 299 See `test-parse-options.c` and
 300 `builtin/add.c`,
 301 `builtin/clone.c`,
 302 `builtin/commit.c`,
 303 `builtin/fetch.c`,
 304 `builtin/fsck.c`,
 305 `builtin/rm.c`
 306 for real-world examples.