1config API 2========== 3 4The config API gives callers a way to access Git configuration files 5(and files which have the same syntax). See linkgit:git-config[1] for a 6discussion of the config file syntax. 7 8General Usage 9------------- 10 11Config files are parsed linearly, and each variable found is passed to a 12caller-provided callback function. The callback function is responsible 13for any actions to be taken on the config option, and is free to ignore 14some options. It is not uncommon for the configuration to be parsed 15several times during the run of a Git program, with different callbacks 16picking out different variables useful to themselves. 17 18A config callback function takes three parameters: 19 20- the name of the parsed variable. This is in canonical "flat" form: the 21 section, subsection, and variable segments will be separated by dots, 22 and the section and variable segments will be all lowercase. E.g., 23 `core.ignorecase`, `diff.SomeType.textconv`. 24 25- the value of the found variable, as a string. If the variable had no 26 value specified, the value will be NULL (typically this means it 27 should be interpreted as boolean true). 28 29- a void pointer passed in by the caller of the config API; this can 30 contain callback-specific data 31 32A config callback should return 0 for success, or -1 if the variable 33could not be parsed properly. 34 35Basic Config Querying 36--------------------- 37 38Most programs will simply want to look up variables in all config files 39that Git knows about, using the normal precedence rules. To do this, 40call `git_config` with a callback function and void data pointer. 41 42`git_config` will read all config sources in order of increasing 43priority. Thus a callback should typically overwrite previously-seen 44entries with new ones (e.g., if both the user-wide `~/.gitconfig` and 45repo-specific `.git/config` contain `color.ui`, the config machinery 46will first feed the user-wide one to the callback, and then the 47repo-specific one; by overwriting, the higher-priority repo-specific 48value is left at the end). 49 50The `config_with_options` function lets the caller examine config 51while adjusting some of the default behavior of `git_config`. It should 52almost never be used by "regular" Git code that is looking up 53configuration variables. It is intended for advanced callers like 54`git-config`, which are intentionally tweaking the normal config-lookup 55process. It takes two extra parameters: 56 57`config_source`:: 58If this parameter is non-NULL, it specifies the source to parse for 59configuration, rather than looking in the usual files. See `struct 60git_config_source` in `config.h` for details. Regular `git_config` defaults 61to `NULL`. 62 63`opts`:: 64Specify options to adjust the behavior of parsing config files. See `struct 65config_options` in `config.h` for details. As an example: regular `git_config` 66sets `opts.respect_includes` to `1` by default. 67 68Reading Specific Files 69---------------------- 70 71To read a specific file in git-config format, use 72`git_config_from_file`. This takes the same callback and data parameters 73as `git_config`. 74 75Querying For Specific Variables 76------------------------------- 77 78For programs wanting to query for specific variables in a non-callback 79manner, the config API provides two functions `git_config_get_value` 80and `git_config_get_value_multi`. They both read values from an internal 81cache generated previously from reading the config files. 82 83`int git_config_get_value(const char *key, const char **value)`:: 84 85 Finds the highest-priority value for the configuration variable `key`, 86 stores the pointer to it in `value` and returns 0. When the 87 configuration variable `key` is not found, returns 1 without touching 88 `value`. The caller should not free or modify `value`, as it is owned 89 by the cache. 90 91`const struct string_list *git_config_get_value_multi(const char *key)`:: 92 93 Finds and returns the value list, sorted in order of increasing priority 94 for the configuration variable `key`. When the configuration variable 95 `key` is not found, returns NULL. The caller should not free or modify 96 the returned pointer, as it is owned by the cache. 97 98`void git_config_clear(void)`:: 99 100 Resets and invalidates the config cache. 101 102The config API also provides type specific API functions which do conversion 103as well as retrieval for the queried variable, including: 104 105`int git_config_get_int(const char *key, int *dest)`:: 106 107 Finds and parses the value to an integer for the configuration variable 108 `key`. Dies on error; otherwise, stores the value of the parsed integer in 109 `dest` and returns 0. When the configuration variable `key` is not found, 110 returns 1 without touching `dest`. 111 112`int git_config_get_ulong(const char *key, unsigned long *dest)`:: 113 114 Similar to `git_config_get_int` but for unsigned longs. 115 116`int git_config_get_bool(const char *key, int *dest)`:: 117 118 Finds and parses the value into a boolean value, for the configuration 119 variable `key` respecting keywords like "true" and "false". Integer 120 values are converted into true/false values (when they are non-zero or 121 zero, respectively). Other values cause a die(). If parsing is successful, 122 stores the value of the parsed result in `dest` and returns 0. When the 123 configuration variable `key` is not found, returns 1 without touching 124 `dest`. 125 126`int git_config_get_bool_or_int(const char *key, int *is_bool, int *dest)`:: 127 128 Similar to `git_config_get_bool`, except that integers are copied as-is, 129 and `is_bool` flag is unset. 130 131`int git_config_get_maybe_bool(const char *key, int *dest)`:: 132 133 Similar to `git_config_get_bool`, except that it returns -1 on error 134 rather than dying. 135 136`int git_config_get_string_const(const char *key, const char **dest)`:: 137 138 Allocates and copies the retrieved string into the `dest` parameter for 139 the configuration variable `key`; if NULL string is given, prints an 140 error message and returns -1. When the configuration variable `key` is 141 not found, returns 1 without touching `dest`. 142 143`int git_config_get_string(const char *key, char **dest)`:: 144 145 Similar to `git_config_get_string_const`, except that retrieved value 146 copied into the `dest` parameter is a mutable string. 147 148`int git_config_get_pathname(const char *key, const char **dest)`:: 149 150 Similar to `git_config_get_string`, but expands `~` or `~user` into 151 the user's home directory when found at the beginning of the path. 152 153`git_die_config(const char *key, const char *err, ...)`:: 154 155 First prints the error message specified by the caller in `err` and then 156 dies printing the line number and the file name of the highest priority 157 value for the configuration variable `key`. 158 159`void git_die_config_linenr(const char *key, const char *filename, int linenr)`:: 160 161 Helper function which formats the die error message according to the 162 parameters entered. Used by `git_die_config()`. It can be used by callers 163 handling `git_config_get_value_multi()` to print the correct error message 164 for the desired value. 165 166See test-config.c for usage examples. 167 168Value Parsing Helpers 169--------------------- 170 171To aid in parsing string values, the config API provides callbacks with 172a number of helper functions, including: 173 174`git_config_int`:: 175Parse the string to an integer, including unit factors. Dies on error; 176otherwise, returns the parsed result. 177 178`git_config_ulong`:: 179Identical to `git_config_int`, but for unsigned longs. 180 181`git_config_bool`:: 182Parse a string into a boolean value, respecting keywords like "true" and 183"false". Integer values are converted into true/false values (when they 184are non-zero or zero, respectively). Other values cause a die(). If 185parsing is successful, the return value is the result. 186 187`git_config_bool_or_int`:: 188Same as `git_config_bool`, except that integers are returned as-is, and 189an `is_bool` flag is unset. 190 191`git_parse_maybe_bool`:: 192Same as `git_config_bool`, except that it returns -1 on error rather 193than dying. 194 195`git_config_string`:: 196Allocates and copies the value string into the `dest` parameter; if no 197string is given, prints an error message and returns -1. 198 199`git_config_pathname`:: 200Similar to `git_config_string`, but expands `~` or `~user` into the 201user's home directory when found at the beginning of the path. 202 203Include Directives 204------------------ 205 206By default, the config parser does not respect include directives. 207However, a caller can use the special `git_config_include` wrapper 208callback to support them. To do so, you simply wrap your "real" callback 209function and data pointer in a `struct config_include_data`, and pass 210the wrapper to the regular config-reading functions. For example: 211 212------------------------------------------- 213int read_file_with_include(const char *file, config_fn_t fn, void *data) 214{ 215 struct config_include_data inc = CONFIG_INCLUDE_INIT; 216 inc.fn = fn; 217 inc.data = data; 218 return git_config_from_file(git_config_include, file, &inc); 219} 220------------------------------------------- 221 222`git_config` respects includes automatically. The lower-level 223`git_config_from_file` does not. 224 225Custom Configsets 226----------------- 227 228A `config_set` can be used to construct an in-memory cache for 229config-like files that the caller specifies (i.e., files like `.gitmodules`, 230`~/.gitconfig` etc.). For example, 231 232---------------------------------------- 233struct config_set gm_config; 234git_configset_init(&gm_config); 235int b; 236/* we add config files to the config_set */ 237git_configset_add_file(&gm_config, ".gitmodules"); 238git_configset_add_file(&gm_config, ".gitmodules_alt"); 239 240if (!git_configset_get_bool(gm_config, "submodule.frotz.ignore", &b)) { 241 /* hack hack hack */ 242} 243 244/* when we are done with the configset */ 245git_configset_clear(&gm_config); 246---------------------------------------- 247 248Configset API provides functions for the above mentioned work flow, including: 249 250`void git_configset_init(struct config_set *cs)`:: 251 252 Initializes the config_set `cs`. 253 254`int git_configset_add_file(struct config_set *cs, const char *filename)`:: 255 256 Parses the file and adds the variable-value pairs to the `config_set`, 257 dies if there is an error in parsing the file. Returns 0 on success, or 258 -1 if the file does not exist or is inaccessible. The user has to decide 259 if he wants to free the incomplete configset or continue using it when 260 the function returns -1. 261 262`int git_configset_get_value(struct config_set *cs, const char *key, const char **value)`:: 263 264 Finds the highest-priority value for the configuration variable `key` 265 and config set `cs`, stores the pointer to it in `value` and returns 0. 266 When the configuration variable `key` is not found, returns 1 without 267 touching `value`. The caller should not free or modify `value`, as it 268 is owned by the cache. 269 270`const struct string_list *git_configset_get_value_multi(struct config_set *cs, const char *key)`:: 271 272 Finds and returns the value list, sorted in order of increasing priority 273 for the configuration variable `key` and config set `cs`. When the 274 configuration variable `key` is not found, returns NULL. The caller 275 should not free or modify the returned pointer, as it is owned by the cache. 276 277`void git_configset_clear(struct config_set *cs)`:: 278 279 Clears `config_set` structure, removes all saved variable-value pairs. 280 281In addition to above functions, the `config_set` API provides type specific 282functions in the vein of `git_config_get_int` and family but with an extra 283parameter, pointer to struct `config_set`. 284They all behave similarly to the `git_config_get*()` family described in 285"Querying For Specific Variables" above. 286 287Writing Config Files 288-------------------- 289 290Git gives multiple entry points in the Config API to write config values to 291files namely `git_config_set_in_file` and `git_config_set`, which write to 292a specific config file or to `.git/config` respectively. They both take a 293key/value pair as parameter. 294In the end they both call `git_config_set_multivar_in_file` which takes four 295parameters: 296 297- the name of the file, as a string, to which key/value pairs will be written. 298 299- the name of key, as a string. This is in canonical "flat" form: the section, 300 subsection, and variable segments will be separated by dots, and the section 301 and variable segments will be all lowercase. 302 E.g., `core.ignorecase`, `diff.SomeType.textconv`. 303 304- the value of the variable, as a string. If value is equal to NULL, it will 305 remove the matching key from the config file. 306 307- the value regex, as a string. It will disregard key/value pairs where value 308 does not match. 309 310- a multi_replace value, as an int. If value is equal to zero, nothing or only 311 one matching key/value is replaced, else all matching key/values (regardless 312 how many) are removed, before the new pair is written. 313 314It returns 0 on success. 315 316Also, there are functions `git_config_rename_section` and 317`git_config_rename_section_in_file` with parameters `old_name` and `new_name` 318for renaming or removing sections in the config files. If NULL is passed 319through `new_name` parameter, the section will be removed from the config file.