@matheusbsbs / matheus-bagliano / commits / bdc8088f44

api-parse-options.adoc: document per-option flags

The "Flags" section in "Documentation/technical/api-parse-options.adoc" documents the flags that can be passed to parse_options() itself. It does not, however, document the flags that can be set on individual options through the `flags` member of `struct option` (and through the `OPT_*_F()` macro variants). These per-option flags are used throughout the codebase (for example `PARSE_OPT_HIDDEN` is used to hide an option from `-h` while still showing it with `--help-all`), but a reader currently has to dig into "parse-options.h" to find them. To remediate that, let's add an "Option flags" subsection to the "Data Structure" section, just before the list of option macros. Let's also make it explicit that these are distinct from the parse_options() flags described earlier, and let's describe the `-h` versus `--help-all` behavior for `PARSE_OPT_HIDDEN`. Signed-off-by: Christian Couder <chriscool@tuxfamily.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Christian Couder committed Jul 16, 2026 at 18:55 UTC bdc8088f44fa9e289ad8714d1c8a29a0001f4239
1 file changed +61
Documentation/technical/api-parse-options.adoc
+61
@@ -150,6 +150,67 @@ Data Structure
150
151 The main data structure is an array of the `option` struct,
152 say `static struct option builtin_add_options[]`.
153 +
154 +Option flags
155 +~~~~~~~~~~~~
156 +
157 +Each option can carry flags in the `flags` field of its `option`
158 +struct. These are per-option flags and are distinct from the
159 +`parse_options()` flags described above; they are usually set through
160 +the `OPT_*_F()` macro variants (see below) rather than by hand. They
161 +are the bitwise-or of:
162 +
163 +`PARSE_OPT_OPTARG`::
164 + The option's argument is optional, i.e. both `--option` and
165 + `--option=<value>` are accepted.
166 +
167 +`PARSE_OPT_NOARG`::
168 + The option takes no argument at all. Using `--option=<value>`
169 + is rejected.
170 +
171 +`PARSE_OPT_NONEG`::
172 + Disable the automatically generated negated `--no-option`
173 + form.
174 +
175 +`PARSE_OPT_HIDDEN`::
176 + Hide the option: it is omitted from the usage shown by
177 + `git <cmd> -h`, but is still shown by `git <cmd> --help-all`.
178 + The option is parsed as usual either way. This is meant for
179 + deprecated, advanced or otherwise uncommon options.
180 +
181 +`PARSE_OPT_LASTARG_DEFAULT`::
182 + Use the default value (`defval`) when the option is used
183 + without an argument, even for an option that normally requires
184 + one. Only the last argument on the command line takes effect.
185 +
186 +`PARSE_OPT_NODASH`::
187 + The option is a single character without a leading dash, such
188 + as the `+` used by some commands.
189 +
190 +`PARSE_OPT_LITERAL_ARGHELP`::
191 + Use the argument help string (`argh`) verbatim in the usage
192 + output instead of surrounding it with `<>` or `[]`. Useful when
193 + `argh` already contains a hand-formatted description.
194 +
195 +`PARSE_OPT_FROM_ALIAS`::
196 + Internal flag, set on options that were expanded from a
197 + configured alias. It should not be set by callers.
198 +
199 +`PARSE_OPT_NOCOMPLETE`::
200 + Do not offer this option for completion.
201 +
202 +`PARSE_OPT_COMP_ARG`::
203 + The option's argument, rather than the option itself, is what
204 + should be completed.
205 +
206 +`PARSE_OPT_CMDMODE`::
207 + The option is one of several mutually exclusive "command mode"
208 + options that share the same variable. Using more than one of
209 + them at once is rejected.
210 +
211 +Macros
212 +~~~~~~
213 +
214 There are some macros to easily define options:
215
216 `OPT__ABBREV(&int_var)`::