path: root/Documentation/technical/api-parse-options.txt
AgeCommit message (Collapse)Author
2017-01-19doc: add documentation for OPT_STRING_LISTJacob Keller
Commit c8ba16391655 ("parse-options: add OPT_STRING_LIST helper", 2011-06-09) added the OPT_STRING_LIST as a way to accumulate a repeated list of strings. However, this was not documented in the api-parse-options documentation. Add documentation now so that future developers may learn of its existence. Signed-off-by: Jacob Keller <> Signed-off-by: Junio C Hamano <>
2016-05-05parse-options.c: make OPTION_COUNTUP respect "unspecified" valuesPranit Bauva
OPT_COUNTUP() merely increments the counter upon --option, and resets it to 0 upon --no-option, which means that there is no "unspecified" value with which a client can initialize the counter to determine whether or not --[no]-option was seen at all. Make OPT_COUNTUP() treat any negative number as an "unspecified" value to address this shortcoming. In particular, if a client initializes the counter to -1, then if it is still -1 after parse_options(), then neither --option nor --no-option was seen; if it is 0, then --no-option was seen last, and if it is 1 or greater, than --option was seen last. This change does not affect the behavior of existing clients because they all use the initial value of 0 (or more). Note that builtin/clean.c initializes the variable used with OPT__FORCE (which uses OPT_COUNTUP()) to a negative value, but it is set to either 0 or 1 by reading the configuration before the code calls parse_options(), i.e. as far as parse_options() is concerned, the initial value of the variable is not negative. To test this behavior, in test-parse-options.c, "verbose" is set to "unspecified" while quiet is set to 0 which will test the new behavior with all sets of values. Helped-by: Jeff King <> Helped-by: Eric Sunshine <> Helped-by: Junio C Hamano <> Signed-off-by: Pranit Bauva <> Signed-off-by: Junio C Hamano <>
2016-03-25api-parse-options.txt: document OPT_CMDMODE()Pranit Bauva
OPT_CMDMODE mechanism was introduced in the release of 1.8.5 to actively notice when multiple "operation mode" options that specify mutually incompatible operation modes are given. Signed-off-by: Pranit Bauva <> Signed-off-by: Junio C Hamano <>
2015-08-03Merge branch 'pt/pull-builtin'Junio C Hamano
Reimplement 'git pull' in C. * pt/pull-builtin: pull: remove redirection to pull --rebase: error on no merge candidate cases pull --rebase: exit early when the working directory is dirty pull: configure --rebase via branch.<name>.rebase or pull.rebase pull: teach git pull about --rebase pull: set reflog message pull: implement pulling into an unborn branch pull: fast-forward working tree if head is updated pull: check if in unresolved merge state pull: support pull.ff config pull: error on no merge candidates pull: pass git-fetch's options to git-fetch pull: pass git-merge's options to git-merge pull: pass verbosity, --progress flags to fetch and merge pull: implement fetch + merge pull: implement skeletal builtin pull argv-array: implement argv_array_pushv() parse-options-cb: implement parse_opt_passthru_argv() parse-options-cb: implement parse_opt_passthru()
2015-06-22parse-options: move unsigned long option parsing out of pack-objects.cCharles Bailey
The unsigned long option parsing (including 'k'/'m'/'g' suffix parsing) is more widely applicable. Add support for OPT_MAGNITUDE to parse-options.h and change pack-objects.c use this support. The error behavior on parse errors follows that of OPT_INTEGER. The name of the option that failed to parse is reported with a brief message describing the expect format for the option argument and then the full usage message for the command invoked. This differs from the previous behavior for OPT_ULONG used in pack-objects for --max-pack-size and --window-memory which used to display the value supplied in the error message and did not display the full usage message. Signed-off-by: Charles Bailey <> Signed-off-by: Junio C Hamano <>
2015-06-15parse-options-cb: implement parse_opt_passthru_argv()Paul Tan
Certain git commands, such as git-pull, are simply wrappers around other git commands like git-fetch, git-merge and git-rebase. As such, these wrapper commands will typically need to "pass through" command-line options of the commands they wrap. Implement the parse_opt_passthru_argv() parse-options callback, which will reconstruct all the provided command-line options into an argv_array, such that it can be passed to another git command. This is useful for passing command-line options that can be specified multiple times. Helped-by: Stefan Beller <> Signed-off-by: Paul Tan <> Signed-off-by: Junio C Hamano <>
2015-06-15parse-options-cb: implement parse_opt_passthru()Paul Tan
Certain git commands, such as git-pull, are simply wrappers around other git commands like git-fetch, git-merge and git-rebase. As such, these wrapper commands will typically need to "pass through" command-line options of the commands they wrap. Implement the parse_opt_passthru() parse-options callback, which will reconstruct the command-line option into an char* string, such that it can be passed to another git command. Helped-by: Johannes Schindelin <> Helped-by: Junio C Hamano <> Helped-by: Stefan Beller <> Signed-off-by: Paul Tan <> Signed-off-by: Junio C Hamano <>
2014-03-31parse-options: remove unused OPT_SET_PTRMarat Radchenko
OPT_SET_PTR was never used since its creation at db7244bd (parse-options new features., 2007-11-07). Signed-off-by: Junio C Hamano <>
2013-10-31Use the word 'stuck' instead of 'sticked'Nicolas Vigier
The past participle of 'stick' is 'stuck'. Signed-off-by: Nicolas Vigier <> Signed-off-by: Junio C Hamano <>
2013-06-26Merge branch 'ph/builtin-srcs-are-in-subdir-these-days'Junio C Hamano
* ph/builtin-srcs-are-in-subdir-these-days: fix "builtin-*" references to be "builtin/*"
2013-06-18fix "builtin-*" references to be "builtin/*"Phil Hord
Documentation and some comments still refer to files in builtin/ as 'builtin-*.[cho]'. Update these to show the correct location. Signed-off-by: Phil Hord <> Reviewed-by: Jonathan Nieder <> Assisted-by: Junio C Hamano <> Signed-off-by: Junio C Hamano <>
2013-05-29Merge branch 'jc/prune-all'Junio C Hamano
We used the approxidate() parser for "--expire=<timestamp>" options of various commands, but it is better to treat --expire=all and --expire=now a bit more specially than using the current timestamp. Update "git gc" and "git reflog" with a new parsing function for expiry dates. * jc/prune-all: prune: introduce OPT_EXPIRY_DATE() and use it api-parse-options.txt: document "no-" for non-boolean options git-gc.txt, git-reflog.txt: document new expiry options date.c: add parse_expiry_date()
2013-04-25prune: introduce OPT_EXPIRY_DATE() and use itJunio C Hamano
Earlier we added support for --expire=all (or --expire=now) that considers all crufts, regardless of their age, as eligible for garbage collection by turning command argument parsers that use approxidate() to use parse_expiry_date(), but "git prune" used a built-in parse-options facility OPT_DATE() and did not benefit from the new function. Signed-off-by: Junio C Hamano <>
2013-04-18api-parse-options.txt: document "no-" for non-boolean optionsMichael Haggerty
Document that the "no-" prefix can also be used for non-boolean options. Signed-off-by: Michael Haggerty <> Signed-off-by: Junio C Hamano <>
2013-02-01Documentation: the name of the system is 'Git', not 'git'Thomas Ackermann
Signed-off-by: Thomas Ackermann <> Signed-off-by: Junio C Hamano <>
2012-04-26docs: stop using asciidoc no-inline-literalJeff King
In asciidoc 7, backticks like `foo` produced a typographic effect, but did not otherwise affect the syntax. In asciidoc 8, backticks introduce an "inline literal" inside which markup is not interpreted. To keep compatibility with existing documents, asciidoc 8 has a "no-inline-literal" attribute to keep the old behavior. We enabled this so that the documentation could be built on either version. It has been several years now, and asciidoc 7 is no longer in wide use. We can now decide whether or not we want inline literals on their own merits, which are: 1. The source is much easier to read when the literal contains punctuation. You can use `master~1` instead of `master{tilde}1`. 2. They are less error-prone. Because of point (1), we tend to make mistakes and forget the extra layer of quoting. This patch removes the no-inline-literal attribute from the Makefile and converts every use of backticks in the documentation to an inline literal (they must be cleaned up, or the example above would literally show "{tilde}" in the output). Problematic sites were found by grepping for '`.*[{\\]' and examined and fixed manually. The results were then verified by comparing the output of "html2text" on the set of generated html pages. Doing so revealed that in addition to making the source more readable, this patch fixes several formatting bugs: - HTML rendering used the ellipsis character instead of literal "..." in code examples (like "git log A...B") - some code examples used the right-arrow character instead of '->' because they failed to quote - api-config.txt did not quote tilde, and the resulting HTML contained a bogus snippet like: <tt><sub></tt> foo <tt></sub>bar</tt> which caused some parsers to choke and omit whole sections of the page. - git-commit.txt confused ``foo`` (backticks inside a literal) with ``foo'' (matched double-quotes) - mentions of `A U Thor <>` used to erroneously auto-generate a mailto footnote for - the description of --word-diff=plain incorrectly showed the output as "[-removed-] and {added}", not "{+added+}". - using "prime" notation like: commit `C` and its replacement `C'` confused asciidoc into thinking that everything between the first backtick and the final apostrophe were meant to be inside matched quotes - asciidoc got confused by the escaping of some of our asterisks. In particular, `credential.\*` and `credential.<url>.\*` properly escaped the asterisk in the first case, but literally passed through the backslash in the second case. Signed-off-by: Jeff King <> Signed-off-by: Junio C Hamano <>
2012-02-26parse-options: allow positivation of options starting, with no-René Scharfe
Long options can be negated by adding no- right after the leading two dashes. This is useful e.g. to override options set by aliases. For options that are defined to start with no- already, this looks a bit funny. Allow such options to also be negated by removing the prefix. The following thirteen options are affected: apply --no-add bisect--helper --no-checkout checkout-index --no-create clone --no-checkout --no-hardlinks commit --no-verify --no-post-rewrite format-patch --no-binary hash-object --no-filters read-tree --no-sparse-checkout revert --no-commit show-branch --no-name update-ref --no-deref The following five are NOT affected because they are defined with PARSE_OPT_NONEG or the non-negated version is defined as well: branch --no-merged format-patch --no-stat --no-numbered update-index --no-assume-unchanged --no-skip-worktree Signed-off-by: Rene Scharfe <> Signed-off-by: Junio C Hamano <>
2011-09-28parseopt: add OPT_NOOP_NOARGRené Scharfe
Add OPT_NOOP_NOARG, a helper macro to define deprecated options in a standard way. The help text is taken from the no-op option -r of git revert. The callback could be made to emit a (conditional?) warning later. And we could also add OPT_NOOP (requiring an argument) etc. as needed. Signed-off-by: Rene Scharfe <> Signed-off-by: Junio C Hamano <>
2011-09-28parse-options: deprecate OPT_BOOLEANJunio C Hamano
It is natural to expect that an option defined with OPT_BOOLEAN() could be used in this way: int option = -1; /* unspecified */ struct option options[] = { OPT_BOOLEAN(0, "option", &option, "set option"), OPT_END() }; parse_options(ac, av, prefix, options, usage, 0); if (option < 0) ... do the default thing ... else if (!option) ... --no-option was given ... else ... --option was given ... to easily tell three cases apart: - There is no mention of the `--option` on the command line; - The variable is positively set with `--option`; or - The variable is explicitly negated with `--no-option`. Unfortunately, this is not the case. OPT_BOOLEAN() increments the variable every time `--option` is given, and resets it to zero when `--no-option` is given. As a first step to remedy this, introduce a true boolean OPT_BOOL(), and rename OPT_BOOLEAN() to OPT_COUNTUP(). To help transitioning, OPT_BOOLEAN and OPTION_BOOLEAN are defined as deprecated synonyms to OPT_COUNTUP and OPTION_COUNTUP respectively. This is what db7244b (parse-options new features., 2007-11-07) from four years ago started by marking OPTION_BOOLEAN as "INCR would have been a better name". Some existing users do depend on the count-up semantics; for example, users of OPT__VERBOSE() could use it to raise the verbosity level with repeated use of `-v` on the command line, but they probably should be rewritten to use OPT__VERBOSITY() instead these days. I suspect that some users of OPT__FORCE() may also use it to implement different level of forcibleness but I didn't check. On top of this patch, here are the remaining clean-up tasks that other people can help: - Look at each hit in "git grep -e OPT_BOOLEAN"; trace all uses of the value that is set to the underlying variable, and if it can proven that the variable is only used as a boolean, replace it with OPT_BOOL(). If the caller does depend on the count-up semantics, replace it with OPT_COUNTUP() instead. - Same for OPTION_BOOLEAN; replace it with OPTION_SET_INT and arrange to set 1 to the variable for a true boolean, and otherwise replace it with OPTION_COUNTUP. - Look at each hit in "git grep -e OPT__VERBOSE -e OPT__QUIET" and see if they can be replaced with OPT__VERBOSITY(). I'll follow this message up with a separate patch as an example. Signed-off-by: Junio C Hamano <>
2010-11-15add OPT__FORCERené Scharfe
Add OPT__FORCE as a helper macro in the same spirit as OPT__VERBOSE to simplify defining -f/--force options. Signed-off-by: Rene Scharfe <> Signed-off-by: Junio C Hamano <>
2010-11-15add description parameter to OPT__QUIETRené Scharfe
Allows better help text to be defined than "be quiet". Also make use of the macro in a place that already had a different description. No object code changes intended. Signed-off-by: Rene Scharfe <> Signed-off-by: Junio C Hamano <>
2010-11-15add description parameter to OPT__DRY_RUNRené Scharfe
Allows better help text to be defined than "dry run". Also make use of the macro in places that already had a different description. No object code changes intended. Signed-off-by: Rene Scharfe <> Signed-off-by: Junio C Hamano <>
2010-11-15add description parameter to OPT__VERBOSERené Scharfe
Allows better help text to be defined than "be verbose". Also make use of the macro in places that already had a different description. No object code changes intended. Signed-off-by: Rene Scharfe <> Signed-off-by: Junio C Hamano <>
2010-08-20Documentation/technical: avoid stray backslash in parse-options API docsJonathan Nieder
Due to some unpleasant interaction between the `quote', 'italics', and `monospace` rules, a certain paragraph ends up rendered like so: ‘short` is a character for the short option (e.g. <tt>'e\’</tt> for <tt>-e</tt>, use <tt>0</tt> to omit), Use the {apostrophe} to avoid this. While at it, escape "->" strings: they are meant as a literal two-character C operator, not a right-pointing arrow. Reported-by: Frédéric Brière <> Signed-off-by: Jonathan Nieder <> Signed-off-by: Junio C Hamano <>
2010-02-19Add an optional argument for --color optionsMark Lodato
Make git-branch, git-show-branch, git-grep, and all the diff-based programs accept an optional argument <when> for --color. The argument is a colorbool: "always", "never", or "auto". If no argument is given, "always" is used; --no-color is an alias for --color=never. This makes the command-line interface consistent with other GNU tools, such as `ls' and `grep', and with the git-config color options. Note that, without an argument, --color and --no-color work exactly as before. To implement this, two internal changes were made: 1. Allow the first argument of git_config_colorbool() to be NULL, in which case it returns -1 if the argument isn't "always", "never", or "auto". 2. Add OPT_COLOR_FLAG(), OPT__COLOR(), and parse_opt_color_flag_cb() to the option parsing library. The callback uses git_config_colorbool(), so color.h is now a dependency of parse-options.c. Signed-off-by: Mark Lodato <> Signed-off-by: Junio C Hamano <>
2009-05-25parse-opts: add OPT_FILENAME and transition builtinsStephen Boyd
Commit dbd0f5c (Files given on the command line are relative to $cwd, 2008-08-06) introduced parse_options_fix_filename() as a minimal fix. OPT_FILENAME is intended to be a more robust fix for the same issue. OPT_FILENAME and its associated enum OPTION_FILENAME are used to represent filename options within the parse options API. This option is similar to OPTION_STRING. If --no is prefixed to the option the filename is unset. If no argument is given and the default value is set, the filename is set to the default value. The difference is that the filename is prefixed with the prefix passed to parse_options() (or parse_options_start()). Update git-apply, git-commit, git-fmt-merge-msg, and git-tag to use OPT_FILENAME with their filename options. Also, rename parse_options_fix_filename() to fix_filename() as it is no longer extern. Signed-off-by: Stephen Boyd <> Signed-off-by: Junio C Hamano <>
2009-05-25parse-opts: prepare for OPT_FILENAMEStephen Boyd
To give OPT_FILENAME the prefix, we pass the prefix to parse_options() which passes the prefix to parse_options_start() which sets the prefix member of parse_opts_ctx accordingly. If there isn't a prefix in the calling context, passing NULL will suffice. Signed-off-by: Stephen Boyd <> Signed-off-by: Junio C Hamano <>
2009-05-23Merge branch 'rs/grep-parseopt'Junio C Hamano
* rs/grep-parseopt: grep: make callback functions static grep: use parseopt grep: remove global variable builtin_grep parseopt: add PARSE_OPT_NODASH parseopt: add OPT_NUMBER_CALLBACK parseopt: add OPT_NEGBIT
2009-05-16api-parse-options.txt: use 'func' instead of 'funct'Stephen Boyd
Signed-off-by: Stephen Boyd <> Signed-off-by: Junio C Hamano <>
2009-05-09parseopt: add OPT_NUMBER_CALLBACKRené Scharfe
Add a way to recognize numerical options. The number is passed to a callback function as a string. Signed-off-by: Rene Scharfe <> Signed-off-by: Junio C Hamano <>
2009-05-09parseopt: add OPT_NEGBITRené Scharfe
Add OPTION_NEGBIT and OPT_NEGBIT, mirroring OPTION_BIT and OPT_BIT. OPT_NEGBIT can be used together with OPT_BIT to define two options that cancel each other out. Note: this patch removes the reminder from the test script because it adds a test for --no-or4 and there already was one for --or4. Signed-off-by: Rene Scharfe <> Signed-off-by: Junio C Hamano <>
2009-03-09parseopt: prevent KEEP_UNKNOWN and STOP_AT_NON_OPTION from being used togetherRené Scharfe
As suggested by Junio, disallow the flags PARSE_OPT_KEEP_UNKNOWN and PARSE_OPT_STOP_AT_NON_OPTION to be turned on at the same time, as a value of an unknown option could be mistakenly classified as a non-option, stopping the parser early. E.g.: git cmd --known --unknown value arg0 arg1 The parser should have stopped at "arg0", but it already stops at "value". This patch makes parse_options() die if the two flags are used in combination. Signed-off-by: Rene Scharfe <> Signed-off-by: Junio C Hamano <>
2009-03-09parseopt: document KEEP_ARGV0, KEEP_UNKNOWN, NO_INTERNAL_HELPRené Scharfe
Signed-off-by: Rene Scharfe <> Signed-off-by: Junio C Hamano <>
2008-06-23api-parse-options.txt: Introduce documentation for parse options APIStephan Beyer
Add some documentation of basics, macros and callback implementation of the parse-options API. Signed-off-by: Stephan Beyer <> Signed-off-by: Junio C Hamano <>
2007-12-15Start preparing the API documents.Junio C Hamano
Most of them are still stubs, but the procedure to build the HTML documentation, maintaining the index and installing the end product are there. I placed names of people who are likely to know the most about the topic in the stub files, so that volunteers will know whom to ask questions as needed. Signed-off-by: Junio C Hamano <>