| config API | |
| ========== | |
| The config API gives callers a way to access Git configuration files | |
| (and files which have the same syntax). See linkgit:git-config[1] for a | |
| discussion of the config file syntax. | |
| General Usage | |
| ------------- | |
| Config files are parsed linearly, and each variable found is passed to a | |
| caller-provided callback function. The callback function is responsible | |
| for any actions to be taken on the config option, and is free to ignore | |
| some options. It is not uncommon for the configuration to be parsed | |
| several times during the run of a Git program, with different callbacks | |
| picking out different variables useful to themselves. | |
| A config callback function takes three parameters: | |
| - the name of the parsed variable. This is in canonical "flat" form: the | |
| section, subsection, and variable segments will be separated by dots, | |
| and the section and variable segments will be all lowercase. E.g., | |
| `core.ignorecase`, `diff.SomeType.textconv`. | |
| - the value of the found variable, as a string. If the variable had no | |
| value specified, the value will be NULL (typically this means it | |
| should be interpreted as boolean true). | |
| - a void pointer passed in by the caller of the config API; this can | |
| contain callback-specific data | |
| A config callback should return 0 for success, or -1 if the variable | |
| could not be parsed properly. | |
| Basic Config Querying | |
| --------------------- | |
| Most programs will simply want to look up variables in all config files | |
| that Git knows about, using the normal precedence rules. To do this, | |
| call `git_config` with a callback function and void data pointer. | |
| `git_config` will read all config sources in order of increasing | |
| priority. Thus a callback should typically overwrite previously-seen | |
| entries with new ones (e.g., if both the user-wide `~/.gitconfig` and | |
| repo-specific `.git/config` contain `color.ui`, the config machinery | |
| will first feed the user-wide one to the callback, and then the | |
| repo-specific one; by overwriting, the higher-priority repo-specific | |
| value is left at the end). | |
| The `git_config_with_options` function lets the caller examine config | |
| while adjusting some of the default behavior of `git_config`. It should | |
| almost never be used by "regular" Git code that is looking up | |
| configuration variables. It is intended for advanced callers like | |
| `git-config`, which are intentionally tweaking the normal config-lookup | |
| process. It takes two extra parameters: | |
| `filename`:: | |
| If this parameter is non-NULL, it specifies the name of a file to | |
| parse for configuration, rather than looking in the usual files. Regular | |
| `git_config` defaults to `NULL`. | |
| `respect_includes`:: | |
| Specify whether include directives should be followed in parsed files. | |
| Regular `git_config` defaults to `1`. | |
| There is a special version of `git_config` called `git_config_early`. | |
| This version takes an additional parameter to specify the repository | |
| config, instead of having it looked up via `git_path`. This is useful | |
| early in a Git program before the repository has been found. Unless | |
| you're working with early setup code, you probably don't want to use | |
| this. | |
| Reading Specific Files | |
| ---------------------- | |
| To read a specific file in git-config format, use | |
| `git_config_from_file`. This takes the same callback and data parameters | |
| as `git_config`. | |
| Value Parsing Helpers | |
| --------------------- | |
| To aid in parsing string values, the config API provides callbacks with | |
| a number of helper functions, including: | |
| `git_config_int`:: | |
| Parse the string to an integer, including unit factors. Dies on error; | |
| otherwise, returns the parsed result. | |
| `git_config_ulong`:: | |
| Identical to `git_config_int`, but for unsigned longs. | |
| `git_config_bool`:: | |
| Parse a string into a boolean value, respecting keywords like "true" and | |
| "false". Integer values are converted into true/false values (when they | |
| are non-zero or zero, respectively). Other values cause a die(). If | |
| parsing is successful, the return value is the result. | |
| `git_config_bool_or_int`:: | |
| Same as `git_config_bool`, except that integers are returned as-is, and | |
| an `is_bool` flag is unset. | |
| `git_config_maybe_bool`:: | |
| Same as `git_config_bool`, except that it returns -1 on error rather | |
| than dying. | |
| `git_config_string`:: | |
| Allocates and copies the value string into the `dest` parameter; if no | |
| string is given, prints an error message and returns -1. | |
| `git_config_pathname`:: | |
| Similar to `git_config_string`, but expands `~` or `~user` into the | |
| user's home directory when found at the beginning of the path. | |
| Include Directives | |
| ------------------ | |
| By default, the config parser does not respect include directives. | |
| However, a caller can use the special `git_config_include` wrapper | |
| callback to support them. To do so, you simply wrap your "real" callback | |
| function and data pointer in a `struct config_include_data`, and pass | |
| the wrapper to the regular config-reading functions. For example: | |
| ------------------------------------------- | |
| int read_file_with_include(const char *file, config_fn_t fn, void *data) | |
| { | |
| struct config_include_data inc = CONFIG_INCLUDE_INIT; | |
| inc.fn = fn; | |
| inc.data = data; | |
| return git_config_from_file(git_config_include, file, &inc); | |
| } | |
| ------------------------------------------- | |
| `git_config` respects includes automatically. The lower-level | |
| `git_config_from_file` does not. | |
| Writing Config Files | |
| -------------------- | |
| TODO |