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