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