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