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