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 50There is a special version of `git_config` called `git_config_early` 51that takes an additional parameter to specify the repository config. 52This should be used early in a git program when the repository location 53has not yet been determined (and calling the usual lazy-evaluation 54lookup rules would yield an incorrect location). 55 56Reading Specific Files 57---------------------- 58 59To read a specific file in git-config format, use 60`git_config_from_file`. This takes the same callback and data parameters 61as `git_config`. 62 63Value Parsing Helpers 64--------------------- 65 66To aid in parsing string values, the config API provides callbacks with 67a number of helper functions, including: 68 69`git_config_int`:: 70Parse the string to an integer, including unit factors. Dies on error; 71otherwise, returns the parsed result. 72 73`git_config_ulong`:: 74Identical to `git_config_int`, but for unsigned longs. 75 76`git_config_bool`:: 77Parse a string into a boolean value, respecting keywords like "true" and 78"false". Integer values are converted into true/false values (when they 79are non-zero or zero, respectively). Other values cause a die(). If 80parsing is successful, the return value is the result. 81 82`git_config_bool_or_int`:: 83Same as `git_config_bool`, except that integers are returned as-is, and 84an `is_bool` flag is unset. 85 86`git_config_maybe_bool`:: 87Same as `git_config_bool`, except that it returns -1 on error rather 88than dying. 89 90`git_config_string`:: 91Allocates and copies the value string into the `dest` parameter; if no 92string is given, prints an error message and returns -1. 93 94`git_config_pathname`:: 95Similar to `git_config_string`, but expands `~` or `~user` into the 96user's home directory when found at the beginning of the path. 97 98Writing Config Files 99-------------------- 100 101TODO