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