@@ -77,6 +77,86 @@ To read a specific file in git-config format, use
7777`git_config_from_file`. This takes the same callback and data parameters
7878as `git_config`.
7979
80+ Querying For Specific Variables
81+ -------------------------------
82+
83+ For programs wanting to query for specific variables in a non-callback
84+ manner, the config API provides two functions `git_config_get_value`
85+ and `git_config_get_value_multi`. They both read values from an internal
86+ cache generated previously from reading the config files.
87+
88+ `int git_config_get_value(const char *key, const char **value)`::
89+
90+ Finds the highest-priority value for the configuration variable `key`,
91+ stores the pointer to it in `value` and returns 0. When the
92+ configuration variable `key` is not found, returns 1 without touching
93+ `value`. The caller should not free or modify `value`, as it is owned
94+ by the cache.
95+
96+ `const struct string_list *git_config_get_value_multi(const char *key)`::
97+
98+ Finds and returns the value list, sorted in order of increasing priority
99+ for the configuration variable `key`. When the configuration variable
100+ `key` is not found, returns NULL. The caller should not free or modify
101+ the returned pointer, as it is owned by the cache.
102+
103+ `void git_config_clear(void)`::
104+
105+ Resets and invalidates the config cache.
106+
107+ The config API also provides type specific API functions which do conversion
108+ as well as retrieval for the queried variable, including:
109+
110+ `int git_config_get_int(const char *key, int *dest)`::
111+
112+ Finds and parses the value to an integer for the configuration variable
113+ `key`. Dies on error; otherwise, stores the value of the parsed integer in
114+ `dest` and returns 0. When the configuration variable `key` is not found,
115+ returns 1 without touching `dest`.
116+
117+ `int git_config_get_ulong(const char *key, unsigned long *dest)`::
118+
119+ Similar to `git_config_get_int` but for unsigned longs.
120+
121+ `int git_config_get_bool(const char *key, int *dest)`::
122+
123+ Finds and parses the value into a boolean value, for the configuration
124+ variable `key` respecting keywords like "true" and "false". Integer
125+ values are converted into true/false values (when they are non-zero or
126+ zero, respectively). Other values cause a die(). If parsing is successful,
127+ stores the value of the parsed result in `dest` and returns 0. When the
128+ configuration variable `key` is not found, returns 1 without touching
129+ `dest`.
130+
131+ `int git_config_get_bool_or_int(const char *key, int *is_bool, int *dest)`::
132+
133+ Similar to `git_config_get_bool`, except that integers are copied as-is,
134+ and `is_bool` flag is unset.
135+
136+ `int git_config_get_maybe_bool(const char *key, int *dest)`::
137+
138+ Similar to `git_config_get_bool`, except that it returns -1 on error
139+ rather than dying.
140+
141+ `int git_config_get_string_const(const char *key, const char **dest)`::
142+
143+ Allocates and copies the retrieved string into the `dest` parameter for
144+ the configuration variable `key`; if NULL string is given, prints an
145+ error message and returns -1. When the configuration variable `key` is
146+ not found, returns 1 without touching `dest`.
147+
148+ `int git_config_get_string(const char *key, char **dest)`::
149+
150+ Similar to `git_config_get_string_const`, except that retrieved value
151+ copied into the `dest` parameter is a mutable string.
152+
153+ `int git_config_get_pathname(const char *key, const char **dest)`::
154+
155+ Similar to `git_config_get_string`, but expands `~` or `~user` into
156+ the user's home directory when found at the beginning of the path.
157+
158+ See test-config.c for usage examples.
159+
80160Value Parsing Helpers
81161---------------------
82162
@@ -134,6 +214,68 @@ int read_file_with_include(const char *file, config_fn_t fn, void *data)
134214`git_config` respects includes automatically. The lower-level
135215`git_config_from_file` does not.
136216
217+ Custom Configsets
218+ -----------------
219+
220+ A `config_set` can be used to construct an in-memory cache for
221+ config-like files that the caller specifies (i.e., files like `.gitmodules`,
222+ `~/.gitconfig` etc.). For example,
223+
224+ ---------------------------------------
225+ struct config_set gm_config;
226+ git_configset_init(&gm_config);
227+ int b;
228+ /* we add config files to the config_set */
229+ git_configset_add_file(&gm_config, ".gitmodules");
230+ git_configset_add_file(&gm_config, ".gitmodules_alt");
231+
232+ if (!git_configset_get_bool(gm_config, "submodule.frotz.ignore", &b)) {
233+ /* hack hack hack */
234+ }
235+
236+ /* when we are done with the configset */
237+ git_configset_clear(&gm_config);
238+ ----------------------------------------
239+
240+ Configset API provides functions for the above mentioned work flow, including:
241+
242+ `void git_configset_init(struct config_set *cs)`::
243+
244+ Initializes the config_set `cs`.
245+
246+ `int git_configset_add_file(struct config_set *cs, const char *filename)`::
247+
248+ Parses the file and adds the variable-value pairs to the `config_set`,
249+ dies if there is an error in parsing the file. Returns 0 on success, or
250+ -1 if the file does not exist or is inaccessible. The user has to decide
251+ if he wants to free the incomplete configset or continue using it when
252+ the function returns -1.
253+
254+ `int git_configset_get_value(struct config_set *cs, const char *key, const char **value)`::
255+
256+ Finds the highest-priority value for the configuration variable `key`
257+ and config set `cs`, stores the pointer to it in `value` and returns 0.
258+ When the configuration variable `key` is not found, returns 1 without
259+ touching `value`. The caller should not free or modify `value`, as it
260+ is owned by the cache.
261+
262+ `const struct string_list *git_configset_get_value_multi(struct config_set *cs, const char *key)`::
263+
264+ Finds and returns the value list, sorted in order of increasing priority
265+ for the configuration variable `key` and config set `cs`. When the
266+ configuration variable `key` is not found, returns NULL. The caller
267+ should not free or modify the returned pointer, as it is owned by the cache.
268+
269+ `void git_configset_clear(struct config_set *cs)`::
270+
271+ Clears `config_set` structure, removes all saved variable-value pairs.
272+
273+ In addition to above functions, the `config_set` API provides type specific
274+ functions in the vein of `git_config_get_int` and family but with an extra
275+ parameter, pointer to struct `config_set`.
276+ They all behave similarly to the `git_config_get*()` family described in
277+ "Querying For Specific Variables" above.
278+
137279Writing Config Files
138280--------------------
139281
0 commit comments