From: Junio C Hamano <gitster@pobox•com>
To: Jeff King <peff@peff•net>
Cc: git@vger•kernel.org
Subject: Re: [PATCH 1/2] docs: add a basic description of the config API
Date: Mon, 06 Feb 2012 14:31:14 -0800 [thread overview]
Message-ID: <7vbopb61cd.fsf@alter.siamese.dyndns.org> (raw)
In-Reply-To: <20120206095346.GA4300@sigill.intra.peff.net> (Jeff King's message of "Mon, 6 Feb 2012 04:53:46 -0500")
Jeff King <peff@peff•net> 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@peff•net>
> ---
> 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()?
next prev parent reply other threads:[~2012-02-06 22:31 UTC|newest]
Thread overview: 16+ messages / expand[flat|nested] mbox.gz Atom feed top
2012-02-06 9:53 [PATCH 0/2] config includes 3: revenge of the killer includes Jeff King
2012-02-06 9:53 ` [PATCH 1/2] docs: add a basic description of the config API Jeff King
2012-02-06 22:31 ` Junio C Hamano [this message]
2012-02-07 18:06 ` Jeff King
2012-02-07 18:23 ` Jeff King
2012-02-07 18:45 ` Junio C Hamano
2012-02-07 18:44 ` Junio C Hamano
2012-02-08 4:01 ` Nguyen Thai Ngoc Duy
2012-02-08 6:40 ` Junio C Hamano
2012-02-08 6:55 ` Nguyen Thai Ngoc Duy
2012-02-08 15:59 ` Jeff King
2012-02-08 15:48 ` Jeff King
2012-02-07 19:46 ` Jeff King
2012-02-06 9:54 ` [PATCH 2/2] config: add include directive Jeff King
2012-02-06 22:39 ` Junio C Hamano
2012-02-07 18:36 ` Jeff King
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=7vbopb61cd.fsf@alter.siamese.dyndns.org \
--to=gitster@pobox$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=peff@peff$(echo .)net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox