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`:: 190Same as `git_config_bool`, except that it returns -1 on error rather 191than dying. 192 193`git_config_string`:: 194Allocates and copies the value string into the `dest` parameter; if no 195string is given, prints an error message and returns -1. 196 197`git_config_pathname`:: 198Similar to `git_config_string`, but expands `~` or `~user` into the 199user's home directory when found at the beginning of the path. 200 201Include Directives 202------------------ 203 204By default, the config parser does not respect include directives. 205However, a caller can use the special `git_config_include` wrapper 206callback to support them. To do so, you simply wrap your "real" callback 207function and data pointer in a `struct config_include_data`, and pass 208the wrapper to the regular config-reading functions. For example: 209 210------------------------------------------- 211int read_file_with_include(const char *file, config_fn_t fn, void *data) 212{ 213 struct config_include_data inc = CONFIG_INCLUDE_INIT; 214 inc.fn = fn; 215 inc.data = data; 216 return git_config_from_file(git_config_include, file, &inc); 217} 218------------------------------------------- 219 220`git_config` respects includes automatically. The lower-level 221`git_config_from_file` does not. 222 223Custom Configsets 224----------------- 225 226A `config_set` can be used to construct an in-memory cache for 227config-like files that the caller specifies (i.e., files like `.gitmodules`, 228`~/.gitconfig` etc.). For example, 229 230--------------------------------------- 231struct config_set gm_config; 232git_configset_init(&gm_config); 233int b; 234/* we add config files to the config_set */ 235git_configset_add_file(&gm_config, ".gitmodules"); 236git_configset_add_file(&gm_config, ".gitmodules_alt"); 237 238if (!git_configset_get_bool(gm_config, "submodule.frotz.ignore", &b)) { 239 /* hack hack hack */ 240} 241 242/* when we are done with the configset */ 243git_configset_clear(&gm_config); 244---------------------------------------- 245 246Configset API provides functions for the above mentioned work flow, including: 247 248`void git_configset_init(struct config_set *cs)`:: 249 250 Initializes the config_set `cs`. 251 252`int git_configset_add_file(struct config_set *cs, const char *filename)`:: 253 254 Parses the file and adds the variable-value pairs to the `config_set`, 255 dies if there is an error in parsing the file. Returns 0 on success, or 256 -1 if the file does not exist or is inaccessible. The user has to decide 257 if he wants to free the incomplete configset or continue using it when 258 the function returns -1. 259 260`int git_configset_get_value(struct config_set *cs, const char *key, const char **value)`:: 261 262 Finds the highest-priority value for the configuration variable `key` 263 and config set `cs`, stores the pointer to it in `value` and returns 0. 264 When the configuration variable `key` is not found, returns 1 without 265 touching `value`. The caller should not free or modify `value`, as it 266 is owned by the cache. 267 268`const struct string_list *git_configset_get_value_multi(struct config_set *cs, const char *key)`:: 269 270 Finds and returns the value list, sorted in order of increasing priority 271 for the configuration variable `key` and config set `cs`. When the 272 configuration variable `key` is not found, returns NULL. The caller 273 should not free or modify the returned pointer, as it is owned by the cache. 274 275`void git_configset_clear(struct config_set *cs)`:: 276 277 Clears `config_set` structure, removes all saved variable-value pairs. 278 279In addition to above functions, the `config_set` API provides type specific 280functions in the vein of `git_config_get_int` and family but with an extra 281parameter, pointer to struct `config_set`. 282They all behave similarly to the `git_config_get*()` family described in 283"Querying For Specific Variables" above. 284 285Writing Config Files 286-------------------- 287 288Git gives multiple entry points in the Config API to write config values to 289files namely `git_config_set_in_file` and `git_config_set`, which write to 290a specific config file or to `.git/config` respectively. They both take a 291key/value pair as parameter. 292In the end they both call `git_config_set_multivar_in_file` which takes four 293parameters: 294 295- the name of the file, as a string, to which key/value pairs will be written. 296 297- the name of key, as a string. This is in canonical "flat" form: the section, 298 subsection, and variable segments will be separated by dots, and the section 299 and variable segments will be all lowercase. 300 E.g., `core.ignorecase`, `diff.SomeType.textconv`. 301 302- the value of the variable, as a string. If value is equal to NULL, it will 303 remove the matching key from the config file. 304 305- the value regex, as a string. It will disregard key/value pairs where value 306 does not match. 307 308- a multi_replace value, as an int. If value is equal to zero, nothing or only 309 one matching key/value is replaced, else all matching key/values (regardless 310 how many) are removed, before the new pair is written. 311 312It returns 0 on success. 313 314Also, there are functions `git_config_rename_section` and 315`git_config_rename_section_in_file` with parameters `old_name` and `new_name` 316for renaming or removing sections in the config files. If NULL is passed 317through `new_name` parameter, the section will be removed from the config file.