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 80Value Parsing Helpers 81--------------------- 82 83To aid in parsing string values, the config API provides callbacks with 84a number of helper functions, including: 85 86`git_config_int`:: 87Parse the string to an integer, including unit factors. Dies on error; 88otherwise, returns the parsed result. 89 90`git_config_ulong`:: 91Identical to `git_config_int`, but for unsigned longs. 92 93`git_config_bool`:: 94Parse a string into a boolean value, respecting keywords like "true" and 95"false". Integer values are converted into true/false values (when they 96are non-zero or zero, respectively). Other values cause a die(). If 97parsing is successful, the return value is the result. 98 99`git_config_bool_or_int`:: 100Same as `git_config_bool`, except that integers are returned as-is, and 101an `is_bool` flag is unset. 102 103`git_config_maybe_bool`:: 104Same as `git_config_bool`, except that it returns -1 on error rather 105than dying. 106 107`git_config_string`:: 108Allocates and copies the value string into the `dest` parameter; if no 109string is given, prints an error message and returns -1. 110 111`git_config_pathname`:: 112Similar to `git_config_string`, but expands `~` or `~user` into the 113user's home directory when found at the beginning of the path. 114 115Include Directives 116------------------ 117 118By default, the config parser does not respect include directives. 119However, a caller can use the special `git_config_include` wrapper 120callback to support them. To do so, you simply wrap your "real" callback 121function and data pointer in a `struct config_include_data`, and pass 122the wrapper to the regular config-reading functions. For example: 123 124------------------------------------------- 125int read_file_with_include(const char *file, config_fn_t fn, void *data) 126{ 127 struct config_include_data inc = CONFIG_INCLUDE_INIT; 128 inc.fn = fn; 129 inc.data = data; 130 return git_config_from_file(git_config_include, file, &inc); 131} 132------------------------------------------- 133 134`git_config` respects includes automatically. The lower-level 135`git_config_from_file` does not. 136 137Writing Config Files 138-------------------- 139 140Git gives multiple entry points in the Config API to write config values to 141files namely `git_config_set_in_file` and `git_config_set`, which write to 142a specific config file or to `.git/config` respectively. They both take a 143key/value pair as parameter. 144In the end they both call `git_config_set_multivar_in_file` which takes four 145parameters: 146 147- the name of the file, as a string, to which key/value pairs will be written. 148 149- the name of key, as a string. This is in canonical "flat" form: the section, 150 subsection, and variable segments will be separated by dots, and the section 151 and variable segments will be all lowercase. 152 E.g., `core.ignorecase`, `diff.SomeType.textconv`. 153 154- the value of the variable, as a string. If value is equal to NULL, it will 155 remove the matching key from the config file. 156 157- the value regex, as a string. It will disregard key/value pairs where value 158 does not match. 159 160- a multi_replace value, as an int. If value is equal to zero, nothing or only 161 one matching key/value is replaced, else all matching key/values (regardless 162 how many) are removed, before the new pair is written. 163 164It returns 0 on success. 165 166Also, there are functions `git_config_rename_section` and 167`git_config_rename_section_in_file` with parameters `old_name` and `new_name` 168for renaming or removing sections in the config files. If NULL is passed 169through `new_name` parameter, the section will be removed from the config file.