add OPT__FORCE
[git/git.git] / Documentation / technical / api-parse-options.txt
CommitLineData
530e741c
JH
1parse-options API
2=================
3
224712e5
SB
4The parse-options API is used to parse and massage options in git
5and to provide a usage help with consistent look.
530e741c 6
224712e5
SB
7Basics
8------
9
10The argument vector `argv[]` may usually contain mandatory or optional
11'non-option arguments', e.g. a filename or a branch, and 'options'.
12Options are optional arguments that start with a dash and
13that 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
30The parse-options API allows:
31
32* 'sticked' and 'separate form' of options with arguments.
33 `-oArg` is sticked, `-o Arg` is separate form.
34 `\--option=Arg` is sticked, `\--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`.
43
44* Options and non-option arguments can clearly be separated using the `\--`
45 option, e.g. `-a -b \--option \-- \--this-is-a-file` indicates that
46 `\--this-is-a-file` must not be processed as an option.
47
48Steps to parse options
49----------------------
50
51. `#include "parse-options.h"`
52
53. define a NULL-terminated
54 `static const char * const builtin_foo_usage[]` array
55 containing alternative usage strings
56
57. define `builtin_foo_options` array as described below
58 in section 'Data Structure'.
59
60. in `cmd_foo(int argc, const char **argv, const char *prefix)`
61 call
62
37782920 63 argc = parse_options(argc, argv, prefix, builtin_foo_options, builtin_foo_usage, flags);
224712e5
SB
64+
65`parse_options()` will filter out the processed options of `argv[]` and leave the
66non-option arguments in `argv[]`.
67`argc` is updated appropriately because of the assignment.
68+
37782920 69You can also pass NULL instead of a usage array as the fifth parameter of
9ad7e6ea
RS
70parse_options(), to avoid displaying a help screen with usage info and
71option list. This should only be done if necessary, e.g. to implement
72a limited parser for only a subset of the options that needs to be run
73before the full parser, which in turn shows the full help message.
74+
224712e5
SB
75Flags are the bitwise-or of:
76
77`PARSE_OPT_KEEP_DASHDASH`::
78 Keep the `\--` that usually separates options from
79 non-option arguments.
80
81`PARSE_OPT_STOP_AT_NON_OPTION`::
82 Usually the whole argument vector is massaged and reordered.
83 Using this flag, processing is stopped at the first non-option
84 argument.
85
9ad7e6ea
RS
86`PARSE_OPT_KEEP_ARGV0`::
87 Keep the first argument, which contains the program name. It's
88 removed from argv[] by default.
89
90`PARSE_OPT_KEEP_UNKNOWN`::
91 Keep unknown arguments instead of erroring out. This doesn't
92 work for all combinations of arguments as users might expect
93 it to do. E.g. if the first argument in `--unknown --known`
94 takes a value (which we can't know), the second one is
95 mistakenly interpreted as a known option. Similarly, if
96 `PARSE_OPT_STOP_AT_NON_OPTION` is set, the second argument in
97 `--unknown value` will be mistakenly interpreted as a
98 non-option, not as a value belonging to the unknown option,
0d260f9a
RS
99 the parser early. That's why parse_options() errors out if
100 both options are set.
9ad7e6ea
RS
101
102`PARSE_OPT_NO_INTERNAL_HELP`::
103 By default, parse_options() handles `-h`, `--help` and
104 `--help-all` internally, by showing a help screen. This option
105 turns it off and allows one to add custom handlers for these
106 options, or to just leave them unknown.
107
224712e5
SB
108Data Structure
109--------------
110
111The main data structure is an array of the `option` struct,
112say `static struct option builtin_add_options[]`.
113There are some macros to easily define options:
114
115`OPT__ABBREV(&int_var)`::
116 Add `\--abbrev[=<n>]`.
117
73e9da01
ML
118`OPT__COLOR(&int_var, description)`::
119 Add `\--color[=<when>]` and `--no-color`.
120
e21adb8c 121`OPT__DRY_RUN(&int_var, description)`::
224712e5
SB
122 Add `-n, \--dry-run`.
123
76946b76
RS
124`OPT__FORCE(&int_var, description)`::
125 Add `-f, \--force`.
126
d52ee6e6 127`OPT__QUIET(&int_var, description)`::
224712e5
SB
128 Add `-q, \--quiet`.
129
fd03881a 130`OPT__VERBOSE(&int_var, description)`::
224712e5
SB
131 Add `-v, \--verbose`.
132
133`OPT_GROUP(description)`::
134 Start an option group. `description` is a short string that
135 describes the group or an empty string.
136 Start the description with an upper-case letter.
137
138`OPT_BOOLEAN(short, long, &int_var, description)`::
139 Introduce a boolean option.
140 `int_var` is incremented on each use.
141
142`OPT_BIT(short, long, &int_var, description, mask)`::
143 Introduce a boolean option.
144 If used, `int_var` is bitwise-ored with `mask`.
145
2f4b97f9
RS
146`OPT_NEGBIT(short, long, &int_var, description, mask)`::
147 Introduce a boolean option.
148 If used, `int_var` is bitwise-anded with the inverted `mask`.
149
224712e5
SB
150`OPT_SET_INT(short, long, &int_var, description, integer)`::
151 Introduce a boolean option.
152 If used, set `int_var` to `integer`.
153
154`OPT_SET_PTR(short, long, &ptr_var, description, ptr)`::
155 Introduce a boolean option.
156 If used, set `ptr_var` to `ptr`.
157
158`OPT_STRING(short, long, &str_var, arg_str, description)`::
159 Introduce an option with string argument.
160 The string argument is put into `str_var`.
161
162`OPT_INTEGER(short, long, &int_var, description)`::
163 Introduce an option with integer argument.
164 The integer is put into `int_var`.
165
166`OPT_DATE(short, long, &int_var, description)`::
167 Introduce an option with date argument, see `approxidate()`.
168 The timestamp is put into `int_var`.
169
170`OPT_CALLBACK(short, long, &var, arg_str, description, func_ptr)`::
171 Introduce an option with argument.
172 The argument will be fed into the function given by `func_ptr`
173 and the result will be put into `var`.
174 See 'Option Callbacks' below for a more elaborate description.
175
df217ed6
SB
176`OPT_FILENAME(short, long, &var, description)`::
177 Introduce an option with a filename argument.
178 The filename will be prefixed by passing the filename along with
179 the prefix argument of `parse_options()` to `prefix_filename()`.
180
224712e5
SB
181`OPT_ARGUMENT(long, description)`::
182 Introduce a long-option argument that will be kept in `argv[]`.
183
e0319ff5
RS
184`OPT_NUMBER_CALLBACK(&var, description, func_ptr)`::
185 Recognize numerical options like -123 and feed the integer as
186 if it was an argument to the function given by `func_ptr`.
187 The result will be put into `var`. There can be only one such
188 option definition. It cannot be negated and it takes no
189 arguments. Short options that happen to be digits take
190 precedence over it.
191
73e9da01
ML
192`OPT_COLOR_FLAG(short, long, &int_var, description)`::
193 Introduce an option that takes an optional argument that can
194 have one of three values: "always", "never", or "auto". If the
195 argument is not given, it defaults to "always". The `--no-` form
196 works like `--long=never`; it cannot take an argument. If
197 "always", set `int_var` to 1; if "never", set `int_var` to 0; if
198 "auto", set `int_var` to 1 if stdout is a tty or a pager,
199 0 otherwise.
200
224712e5
SB
201
202The last element of the array must be `OPT_END()`.
203
204If not stated otherwise, interpret the arguments as follows:
205
206* `short` is a character for the short option
6dcca4d0 207 (e.g. `{apostrophe}e{apostrophe}` for `-e`, use `0` to omit),
224712e5
SB
208
209* `long` is a string for the long option
210 (e.g. `"example"` for `\--example`, use `NULL` to omit),
211
212* `int_var` is an integer variable,
213
214* `str_var` is a string variable (`char *`),
215
216* `arg_str` is the string that is shown as argument
217 (e.g. `"branch"` will result in `<branch>`).
218 If set to `NULL`, three dots (`...`) will be displayed.
219
220* `description` is a short string to describe the effect of the option.
221 It shall begin with a lower-case letter and a full stop (`.`) shall be
222 omitted at the end.
223
224Option Callbacks
225----------------
226
227The function must be defined in this form:
228
229 int func(const struct option *opt, const char *arg, int unset)
230
231The callback mechanism is as follows:
232
ca156cfc 233* Inside `func`, the only interesting member of the structure
6dcca4d0
JN
234 given by `opt` is the void pointer `opt\->value`.
235 `\*opt\->value` will be the value that is saved into `var`, if you
224712e5 236 use `OPT_CALLBACK()`.
6dcca4d0 237 For example, do `*(unsigned long *)opt\->value = 42;` to get 42
224712e5
SB
238 into an `unsigned long` variable.
239
240* Return value `0` indicates success and non-zero return
241 value will invoke `usage_with_options()` and, thus, die.
242
243* If the user negates the option, `arg` is `NULL` and `unset` is 1.
244
245Sophisticated option parsing
246----------------------------
247
248If you need, for example, option callbacks with optional arguments
249or without arguments at all, or if you need other special cases,
250that are not handled by the macros above, you need to specify the
251members of the `option` structure manually.
252
253This is not covered in this document, but well documented
254in `parse-options.h` itself.
255
256Examples
257--------
258
259See `test-parse-options.c` and
260`builtin-add.c`,
261`builtin-clone.c`,
262`builtin-commit.c`,
263`builtin-fetch.c`,
264`builtin-fsck.c`,
265`builtin-rm.c`
266for real-world examples.