tests: fix cleanup after tests in t1509-root-worktree
[git/git.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 `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_DATE(short, long, &int_var, description)`::
172 Introduce an option with date argument, see `approxidate()`.
173 The timestamp is put into `int_var`.
174
175 `OPT_EXPIRY_DATE(short, long, &int_var, description)`::
176 Introduce an option with expiry date argument, see `parse_expiry_date()`.
177 The timestamp is put into `int_var`.
178
179 `OPT_CALLBACK(short, long, &var, arg_str, description, func_ptr)`::
180 Introduce an option with argument.
181 The argument will be fed into the function given by `func_ptr`
182 and the result will be put into `var`.
183 See 'Option Callbacks' below for a more elaborate description.
184
185 `OPT_FILENAME(short, long, &var, description)`::
186 Introduce an option with a filename argument.
187 The filename will be prefixed by passing the filename along with
188 the prefix argument of `parse_options()` to `prefix_filename()`.
189
190 `OPT_ARGUMENT(long, description)`::
191 Introduce a long-option argument that will be kept in `argv[]`.
192
193 `OPT_NUMBER_CALLBACK(&var, description, func_ptr)`::
194 Recognize numerical options like -123 and feed the integer as
195 if it was an argument to the function given by `func_ptr`.
196 The result will be put into `var`. There can be only one such
197 option definition. It cannot be negated and it takes no
198 arguments. Short options that happen to be digits take
199 precedence over it.
200
201 `OPT_COLOR_FLAG(short, long, &int_var, description)`::
202 Introduce an option that takes an optional argument that can
203 have one of three values: "always", "never", or "auto". If the
204 argument is not given, it defaults to "always". The `--no-` form
205 works like `--long=never`; it cannot take an argument. If
206 "always", set `int_var` to 1; if "never", set `int_var` to 0; if
207 "auto", set `int_var` to 1 if stdout is a tty or a pager,
208 0 otherwise.
209
210 `OPT_NOOP_NOARG(short, long)`::
211 Introduce an option that has no effect and takes no arguments.
212 Use it to hide deprecated options that are still to be recognized
213 and ignored silently.
214
215
216 The last element of the array must be `OPT_END()`.
217
218 If not stated otherwise, interpret the arguments as follows:
219
220 * `short` is a character for the short option
221 (e.g. `'e'` for `-e`, use `0` to omit),
222
223 * `long` is a string for the long option
224 (e.g. `"example"` for `--example`, use `NULL` to omit),
225
226 * `int_var` is an integer variable,
227
228 * `str_var` is a string variable (`char *`),
229
230 * `arg_str` is the string that is shown as argument
231 (e.g. `"branch"` will result in `<branch>`).
232 If set to `NULL`, three dots (`...`) will be displayed.
233
234 * `description` is a short string to describe the effect of the option.
235 It shall begin with a lower-case letter and a full stop (`.`) shall be
236 omitted at the end.
237
238 Option Callbacks
239 ----------------
240
241 The function must be defined in this form:
242
243 int func(const struct option *opt, const char *arg, int unset)
244
245 The callback mechanism is as follows:
246
247 * Inside `func`, the only interesting member of the structure
248 given by `opt` is the void pointer `opt->value`.
249 `*opt->value` will be the value that is saved into `var`, if you
250 use `OPT_CALLBACK()`.
251 For example, do `*(unsigned long *)opt->value = 42;` to get 42
252 into an `unsigned long` variable.
253
254 * Return value `0` indicates success and non-zero return
255 value will invoke `usage_with_options()` and, thus, die.
256
257 * If the user negates the option, `arg` is `NULL` and `unset` is 1.
258
259 Sophisticated option parsing
260 ----------------------------
261
262 If you need, for example, option callbacks with optional arguments
263 or without arguments at all, or if you need other special cases,
264 that are not handled by the macros above, you need to specify the
265 members of the `option` structure manually.
266
267 This is not covered in this document, but well documented
268 in `parse-options.h` itself.
269
270 Examples
271 --------
272
273 See `test-parse-options.c` and
274 `builtin/add.c`,
275 `builtin/clone.c`,
276 `builtin/commit.c`,
277 `builtin/fetch.c`,
278 `builtin/fsck.c`,
279 `builtin/rm.c`
280 for real-world examples.