Jeff King <peff@xxxxxxxx> writes: > This wasn't documented at all; this is pretty bare-bones, > but it should at least give new git hackers a basic idea of > how the reading side works. > > Signed-off-by: Jeff King <peff@xxxxxxxx> > --- > Documentation/technical/api-config.txt | 101 ++++++++++++++++++++++++++++++++ > 1 files changed, 101 insertions(+), 0 deletions(-) > create mode 100644 Documentation/technical/api-config.txt > > diff --git a/Documentation/technical/api-config.txt b/Documentation/technical/api-config.txt > new file mode 100644 > index 0000000..f428c5c > --- /dev/null > +++ b/Documentation/technical/api-config.txt > @@ -0,0 +1,101 @@ > +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). It woud be easeier to read if you stopped the sentence after "some options" and made the "It is not uncommon..." a first-class sentence outside the parentheses. > +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. This matches what I have always thought, but I think I recently saw a series that adds callbacks that return 1 to mean "I have understood this variable, so callers should not look at it any more". It felt wrong, but I did not find anything in the config.c API framework to prvent such a local calling convention. > +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). > + > +There is a special version of `git_config` called `git_config_early` > +that takes an additional parameter to specify the repository config. > +This should be used early in a git program when the repository location > +has not yet been determined (and calling the usual lazy-evaluation > +lookup rules would yield an incorrect location). Do you want to say somethink like "Ordinary programs should not have to worry about git_config_early()"? Differently put, if you are learning the config API by reading this document and cannot tell which one you should be calling, you are way too inexperienced to call git_config_early() and you would always want to call git_config()? -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html