Merge branch 'jk/fix-remote-curl-url-wo-proto'
[git] / 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         Each use of `--option` increments `int_var`, starting from zero
148         (even if initially negative), and `--no-option` resets it to
149         zero. To determine if `--option` or `--no-option` was encountered at
150         all, initialize `int_var` to a negative value, and if it is still
151         negative after parse_options(), then neither `--option` nor
152         `--no-option` was seen.
153
154 `OPT_BIT(short, long, &int_var, description, mask)`::
155         Introduce a boolean option.
156         If used, `int_var` is bitwise-ored with `mask`.
157
158 `OPT_NEGBIT(short, long, &int_var, description, mask)`::
159         Introduce a boolean option.
160         If used, `int_var` is bitwise-anded with the inverted `mask`.
161
162 `OPT_SET_INT(short, long, &int_var, description, integer)`::
163         Introduce an integer option.
164         `int_var` is set to `integer` with `--option`, and
165         reset to zero with `--no-option`.
166
167 `OPT_STRING(short, long, &str_var, arg_str, description)`::
168         Introduce an option with string argument.
169         The string argument is put into `str_var`.
170
171 `OPT_INTEGER(short, long, &int_var, description)`::
172         Introduce an option with integer argument.
173         The integer is put into `int_var`.
174
175 `OPT_MAGNITUDE(short, long, &unsigned_long_var, description)`::
176         Introduce an option with a size argument. The argument must be a
177         non-negative integer and may include a suffix of 'k', 'm' or 'g' to
178         scale the provided value by 1024, 1024^2 or 1024^3 respectively.
179         The scaled value is put into `unsigned_long_var`.
180
181 `OPT_DATE(short, long, &int_var, description)`::
182         Introduce an option with date argument, see `approxidate()`.
183         The timestamp is put into `int_var`.
184
185 `OPT_EXPIRY_DATE(short, long, &int_var, description)`::
186         Introduce an option with expiry date argument, see `parse_expiry_date()`.
187         The timestamp is put into `int_var`.
188
189 `OPT_CALLBACK(short, long, &var, arg_str, description, func_ptr)`::
190         Introduce an option with argument.
191         The argument will be fed into the function given by `func_ptr`
192         and the result will be put into `var`.
193         See 'Option Callbacks' below for a more elaborate description.
194
195 `OPT_FILENAME(short, long, &var, description)`::
196         Introduce an option with a filename argument.
197         The filename will be prefixed by passing the filename along with
198         the prefix argument of `parse_options()` to `prefix_filename()`.
199
200 `OPT_ARGUMENT(long, description)`::
201         Introduce a long-option argument that will be kept in `argv[]`.
202
203 `OPT_NUMBER_CALLBACK(&var, description, func_ptr)`::
204         Recognize numerical options like -123 and feed the integer as
205         if it was an argument to the function given by `func_ptr`.
206         The result will be put into `var`.  There can be only one such
207         option definition.  It cannot be negated and it takes no
208         arguments.  Short options that happen to be digits take
209         precedence over it.
210
211 `OPT_COLOR_FLAG(short, long, &int_var, description)`::
212         Introduce an option that takes an optional argument that can
213         have one of three values: "always", "never", or "auto".  If the
214         argument is not given, it defaults to "always".  The `--no-` form
215         works like `--long=never`; it cannot take an argument.  If
216         "always", set `int_var` to 1; if "never", set `int_var` to 0; if
217         "auto", set `int_var` to 1 if stdout is a tty or a pager,
218         0 otherwise.
219
220 `OPT_NOOP_NOARG(short, long)`::
221         Introduce an option that has no effect and takes no arguments.
222         Use it to hide deprecated options that are still to be recognized
223         and ignored silently.
224
225 `OPT_PASSTHRU(short, long, &char_var, arg_str, description, flags)`::
226         Introduce an option that will be reconstructed into a char* string,
227         which must be initialized to NULL. This is useful when you need to
228         pass the command-line option to another command. Any previous value
229         will be overwritten, so this should only be used for options where
230         the last one specified on the command line wins.
231
232 `OPT_PASSTHRU_ARGV(short, long, &argv_array_var, arg_str, description, flags)`::
233         Introduce an option where all instances of it on the command-line will
234         be reconstructed into an argv_array. This is useful when you need to
235         pass the command-line option, which can be specified multiple times,
236         to another command.
237
238 `OPT_CMDMODE(short, long, &int_var, description, enum_val)`::
239         Define an "operation mode" option, only one of which in the same
240         group of "operating mode" options that share the same `int_var`
241         can be given by the user. `enum_val` is set to `int_var` when the
242         option is used, but an error is reported if other "operating mode"
243         option has already set its value to the same `int_var`.
244
245
246 The last element of the array must be `OPT_END()`.
247
248 If not stated otherwise, interpret the arguments as follows:
249
250 * `short` is a character for the short option
251   (e.g. `'e'` for `-e`, use `0` to omit),
252
253 * `long` is a string for the long option
254   (e.g. `"example"` for `--example`, use `NULL` to omit),
255
256 * `int_var` is an integer variable,
257
258 * `str_var` is a string variable (`char *`),
259
260 * `arg_str` is the string that is shown as argument
261   (e.g. `"branch"` will result in `<branch>`).
262   If set to `NULL`, three dots (`...`) will be displayed.
263
264 * `description` is a short string to describe the effect of the option.
265   It shall begin with a lower-case letter and a full stop (`.`) shall be
266   omitted at the end.
267
268 Option Callbacks
269 ----------------
270
271 The function must be defined in this form:
272
273         int func(const struct option *opt, const char *arg, int unset)
274
275 The callback mechanism is as follows:
276
277 * Inside `func`, the only interesting member of the structure
278   given by `opt` is the void pointer `opt->value`.
279   `*opt->value` will be the value that is saved into `var`, if you
280   use `OPT_CALLBACK()`.
281   For example, do `*(unsigned long *)opt->value = 42;` to get 42
282   into an `unsigned long` variable.
283
284 * Return value `0` indicates success and non-zero return
285   value will invoke `usage_with_options()` and, thus, die.
286
287 * If the user negates the option, `arg` is `NULL` and `unset` is 1.
288
289 Sophisticated option parsing
290 ----------------------------
291
292 If you need, for example, option callbacks with optional arguments
293 or without arguments at all, or if you need other special cases,
294 that are not handled by the macros above, you need to specify the
295 members of the `option` structure manually.
296
297 This is not covered in this document, but well documented
298 in `parse-options.h` itself.
299
300 Examples
301 --------
302
303 See `test-parse-options.c` and
304 `builtin/add.c`,
305 `builtin/clone.c`,
306 `builtin/commit.c`,
307 `builtin/fetch.c`,
308 `builtin/fsck.c`,
309 `builtin/rm.c`
310 for real-world examples.