path: root/Documentation/technical/api-config.txt
AgeCommit message (Collapse)Author
2019-10-24config: move documentation to config.hHeba Waly
Move the documentation from Documentation/technical/api-config.txt into config.h as it's easier for the developers to find the usage information beside the code instead of looking for it in another doc file, also documentation/technical/api-config.txt is removed because the information it has is now redundant and it'll be hard to keep it up to date and syncronized with the documentation in config.h Signed-off-by: Heba Waly <> Reviewed-by: Emily Shaffer <> Signed-off-by: Junio C Hamano <>
2019-04-01Documentation/technical/api-config.txt: fix formattingSZEDER Gábor
Asciidoctor versions v1.5.7 or later print the following warning while building the documentation: ASCIIDOC technical/api-config.html asciidoctor: WARNING: api-config.txt: line 232: unterminated listing block This highlight an issue (even with older Asciidoctor versions) where the length of the '----' lines surrounding a code example don't match, and the rest of the document is rendered in monospace. Fix this by making sure that the length of those lines match. The page rendered with AsciiDoc doesn't have this formatting issue. Signed-off-by: SZEDER Gábor <> Signed-off-by: Junio C Hamano <>
2018-05-11doc: fix config API documentation about config_with_optionsAntonio Ospite
In commit dc8441fdb ("config: don't implicitly use gitdir or commondir", 2017-06-14) the function git_config_with_options was renamed to config_with_options to better reflect the fact that it does not access the git global config or the repo config by default. However Documentation/technical/api-config.txt still refers to the previous name, fix that. While at it also update the documentation about the extra parameters, because they too changed since the initial definition. Signed-off-by: Antonio Ospite <> Signed-off-by: Junio C Hamano <>
2017-09-07config: remove git_config_maybe_boolMartin Ågren
The function was deprecated in commit 89576613 ("treewide: deprecate git_config_maybe_bool, use git_parse_maybe_bool", 2017-08-07) and has no users. Signed-off-by: Martin Ågren <> Signed-off-by: Junio C Hamano <>
2017-08-07treewide: deprecate git_config_maybe_bool, use git_parse_maybe_boolMartin Ågren
The only difference between these is that the former takes an argument `name` which it ignores completely. Still, the callers are quite careful to provide reasonable values for it. Once in-flight topics have landed, we should be able to remove git_config_maybe_bool. In the meantime, document it as deprecated in the technical documentation. While at it, document git_parse_maybe_bool. Signed-off-by: Martin Ågren <> Signed-off-by: Junio C Hamano <>
2016-03-11config: drop git_config_earlyJeff King
There are no more callers, and it's a rather confusing interface. This could just be folded into git_config_with_options(), but for the sake of readability, we'll leave it as a separate (static) helper function. Signed-off-by: Jeff King <> Signed-off-by: Junio C Hamano <>
2014-09-11Merge branch 'ta/config-set-1'Junio C Hamano
Use the new caching config-set API in git_config() calls. * ta/config-set-1: add tests for `git_config_get_string_const()` add a test for semantic errors in config files rewrite git_config() to use the config-set API config: add `git_die_config()` to the config-set API change `git_config()` return value to void add line number and file name info to `config_set` config.c: fix accuracy of line number in errors config.c: mark error and warnings strings for translation
2014-09-02Merge branch 'ta/config-set'Junio C Hamano
Add in-core caching layer to let us avoid reading the same configuration files number of times. * ta/config-set: test-config: add tests for the config_set API add `config_set` API for caching config-like files
2014-08-07config: add `git_die_config()` to the config-set APITanay Abhra
Add `git_die_config` that dies printing the line number and the file name of the highest priority value for the configuration variable `key`. A custom error message is also printed before dying, specified by the caller, which can be skipped if `err` argument is set to NULL. It has usage in non-callback based config value retrieval where we can raise an error and die if there is a semantic error. For example, if (!git_config_get_value(key, &value)){ if (!strcmp(value, "foo")) git_config_die(key, "value: `%s` is illegal", value); else /* do work */ } Signed-off-by: Tanay Abhra <> Reviewed-by: Matthieu Moy <> Signed-off-by: Junio C Hamano <>
2014-07-30add documentation for writing config filesTanay Abhra
Replace TODO introduced in commit 9c3c22 with documentation explaining Git config API functions for writing configuration files. Signed-off-by: Tanay Abhra <> Reviewed-by: Matthieu Moy <> Signed-off-by: Junio C Hamano <>
2014-07-29add `config_set` API for caching config-like filesTanay Abhra
Currently `git_config()` uses a callback mechanism and file rereads for config values. Due to this approach, it is not uncommon for the config files to be parsed several times during the run of a git program, with different callbacks picking out different variables useful to themselves. Add a `config_set`, that can be used to construct an in-memory cache for config-like files that the caller specifies (i.e., files like `.gitmodules`, `~/.gitconfig` etc.). Add two external functions `git_configset_get_value` and `git_configset_get_value_multi` for querying from the config sets. `git_configset_get_value` follows `last one wins` semantic (i.e. if there are multiple matches for the queried key in the files of the configset the value returned will be the last entry in `value_list`). `git_configset_get_value_multi` returns a list of values sorted in order of increasing priority (i.e. last match will be at the end of the list). Add type specific query functions like `git_configset_get_bool` and similar. Add a default `config_set`, `the_config_set` to cache all key-value pairs read from usual config files (repo specific .git/config, user wide ~/.gitconfig, XDG config and the global /etc/gitconfig). `the_config_set` is populated using `git_config()`. Add two external functions `git_config_get_value` and `git_config_get_value_multi` for querying in a non-callback manner from `the_config_set`. Also, add type specific query functions that are implemented as a thin wrapper around the `config_set` API. Signed-off-by: Matthieu Moy <> Signed-off-by: Tanay Abhra <> 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-06-08docs: fix cross-directory linkgit referencesJeff King
Most of our documentation is in a single directory, so using linkgit:git-config[1] just generates a relative link in the same directory. However, this is not the case with the API documentation in technical/*, which need to refer to git-config from the parent directory. We can fix this by passing a special prefix attribute when building in a subdirectory, and respecting that prefix in our linkgit definitions. We only have to modify the html linkgit definition. For manpages, we can ignore this for two reasons: 1. we do not generate actual links to the file in manpages, but instead just give the name and section of the linked manpage 2. we do not currently build manpages for subdirectories, only html Signed-off-by: Jeff King <> Signed-off-by: Matthieu Moy <> Signed-off-by: Junio C Hamano <>
2012-06-04doc: fix xref link from api docs to manual pagesJunio C Hamano
They are one-level above, so refer them as linkgit:../git-foo[n] with "../" Signed-off-by: Junio C Hamano <>
2012-02-17config: add include directiveJeff King
It can be useful to split your ~/.gitconfig across multiple files. For example, you might have a "main" file which is used on many machines, but a small set of per-machine tweaks. Or you may want to make some of your config public (e.g., clever aliases) while keeping other data back (e.g., your name or other identifying information). Or you may want to include a number of config options in some subset of your repos without copying and pasting (e.g., you want to reference them from the .git/config of participating repos). This patch introduces an include directive for config files. It looks like: [include] path = /path/to/file This is syntactically backwards-compatible with existing git config parsers (i.e., they will see it as another config entry and ignore it unless you are looking up include.path). The implementation provides a "git_config_include" callback which wraps regular config callbacks. Callers can pass it to git_config_from_file, and it will transparently follow any include directives, passing all of the discovered options to the real callback. Include directives are turned on automatically for "regular" git config parsing. This includes calls to git_config, as well as calls to the "git config" program that do not specify a single file (e.g., using "-f", "--global", etc). They are not turned on in other cases, including: 1. Parsing of other config-like files, like .gitmodules. There isn't a real need, and I'd rather be conservative and avoid unnecessary incompatibility or confusion. 2. Reading single files via "git config". This is for two reasons: a. backwards compatibility with scripts looking at config-like files. b. inspection of a specific file probably means you care about just what's in that file, not a general lookup for "do we have this value anywhere at all". If that is not the case, the caller can always specify "--includes". 3. Writing files via "git config"; we want to treat include.* variables as literal items to be copied (or modified), and not expand them. So "git config --unset-all" would operate _only_ on .git/config, not any of its included files (just as it also does not operate on ~/.gitconfig). Signed-off-by: Jeff King <> Signed-off-by: Junio C Hamano <>
2012-02-17config: provide a version of git_config with more optionsJeff King
Callers may want to provide a specific version of a file in which to look for config. Right now this can be done by setting the magic global config_exclusive_filename variable. By providing a version of git_config that takes a filename, we can take a step towards making this magic global go away. Furthermore, by providing a more "advanced" interface, we now have a a natural place to add new options for callers like git-config, which care about tweaking the specifics of config lookup, without disturbing the large number of "simple" users (i.e., every other part of git). The astute reader of this patch may notice that the logic for handling config_exclusive_filename was taken out of git_config_early, but added into git_config. This means that git_config_early will no longer respect config_exclusive_filename. That's OK, because the only other caller of git_config_early is check_repository_format_gently, but the only function which sets config_exclusive_filename is cmd_config, which does not call check_repository_format_gently (and if it did, it would have been a bug, anyway, as we would be checking the repository format in the wrong file). Signed-off-by: Jeff King <> Signed-off-by: Junio C Hamano <>
2012-02-17docs/api-config: minor clarificationsJeff King
The first change simply drops some parentheses to make a statement more clear. The seconds clarifies that almost nobody wants to call git_config_early. Signed-off-by: Jeff King <> Signed-off-by: Junio C Hamano <>
2012-02-06docs: add a basic description of the config APIJeff King
This wasn't documented at all; this is pretty bare-bones, but it should at least give new git hackers a basic idea of how the reading side works. Signed-off-by: Jeff King <> Signed-off-by: Junio C Hamano <>