f428c5c4864a577f3955c9efc66b52c56a8a713e
   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