]>
Commit | Line | Data |
---|---|---|
5d4cd003 | 1 | /* |
359fc2d2 | 2 | * Copyright (C) the libgit2 contributors. All rights reserved. |
5d4cd003 | 3 | * |
bb742ede VM |
4 | * This file is part of libgit2, distributed under the GNU GPL v2 with |
5 | * a Linking Exception. For full terms see the included COPYING file. | |
5d4cd003 CMN |
6 | */ |
7 | #ifndef INCLUDE_git_config_h__ | |
8 | #define INCLUDE_git_config_h__ | |
9 | ||
10 | #include "common.h" | |
9a3c5e55 | 11 | #include "types.h" |
ee550477 | 12 | #include "buffer.h" |
5d4cd003 CMN |
13 | |
14 | /** | |
9a3c5e55 | 15 | * @file git2/config.h |
5d4cd003 | 16 | * @brief Git config management routines |
9a3c5e55 | 17 | * @defgroup git_config Git config management routines |
5d4cd003 CMN |
18 | * @ingroup Git |
19 | * @{ | |
20 | */ | |
21 | GIT_BEGIN_DECL | |
22 | ||
a1abe66a | 23 | /** |
24 | * Priority level of a config file. | |
25 | * These priority levels correspond to the natural escalation logic | |
26 | * (from higher to lower) when searching for config entries in git.git. | |
27 | * | |
28 | * git_config_open_default() and git_repository_config() honor those | |
29 | * priority levels as well. | |
30 | */ | |
16adc9fa | 31 | typedef enum { |
8c7c5fa5 CMN |
32 | /** System-wide on Windows, for compatibility with portable git */ |
33 | GIT_CONFIG_LEVEL_PROGRAMDATA = 1, | |
34 | ||
16adc9fa | 35 | /** System-wide configuration file; /etc/gitconfig on Linux systems */ |
8c7c5fa5 | 36 | GIT_CONFIG_LEVEL_SYSTEM = 2, |
16adc9fa RB |
37 | |
38 | /** XDG compatible configuration file; typically ~/.config/git/config */ | |
8c7c5fa5 | 39 | GIT_CONFIG_LEVEL_XDG = 3, |
16adc9fa RB |
40 | |
41 | /** User-specific configuration file (also called Global configuration | |
42 | * file); typically ~/.gitconfig | |
43 | */ | |
8c7c5fa5 | 44 | GIT_CONFIG_LEVEL_GLOBAL = 4, |
16adc9fa RB |
45 | |
46 | /** Repository specific configuration file; $WORK_DIR/.git/config on | |
47 | * non-bare repos | |
48 | */ | |
8c7c5fa5 | 49 | GIT_CONFIG_LEVEL_LOCAL = 5, |
16adc9fa | 50 | |
76b893b6 SS |
51 | /** Application specific configuration file; freely defined by applications |
52 | */ | |
8c7c5fa5 | 53 | GIT_CONFIG_LEVEL_APP = 6, |
76b893b6 | 54 | |
16adc9fa RB |
55 | /** Represents the highest level available config file (i.e. the most |
56 | * specific config file available that actually is loaded) | |
57 | */ | |
58 | GIT_CONFIG_HIGHEST_LEVEL = -1, | |
59 | } git_config_level_t; | |
a1abe66a | 60 | |
a295bd2d CMN |
61 | /** |
62 | * An entry in a configuration file | |
63 | */ | |
9a97f49e | 64 | typedef struct git_config_entry { |
c03e8c22 BC |
65 | const char *name; /**< Name of the entry (normalised) */ |
66 | const char *value; /**< String value of the entry */ | |
ac3d33df | 67 | unsigned int include_depth; /**< Depth of includes where this variable was found */ |
c03e8c22 | 68 | git_config_level_t level; /**< Which config file this was found in */ |
ac3d33df | 69 | void GIT_CALLBACK(free)(struct git_config_entry *entry); /**< Free function for this entry */ |
9a97f49e | 70 | void *payload; /**< Opaque value for the free function. Do not read or write */ |
a1abe66a | 71 | } git_config_entry; |
72 | ||
9a97f49e CMN |
73 | /** |
74 | * Free a config entry | |
75 | */ | |
76 | GIT_EXTERN(void) git_config_entry_free(git_config_entry *); | |
77 | ||
ac3d33df JK |
78 | /** |
79 | * A config enumeration callback | |
80 | * | |
81 | * @param entry the entry currently being enumerated | |
82 | * @param payload a user-specified pointer | |
83 | */ | |
84 | typedef int GIT_CALLBACK(git_config_foreach_cb)(const git_config_entry *entry, void *payload); | |
85 | ||
86 | /** | |
87 | * An opaque structure for a configuration iterator | |
88 | */ | |
eba73992 | 89 | typedef struct git_config_iterator git_config_iterator; |
54b2a37a | 90 | |
a295bd2d CMN |
91 | /** |
92 | * Config var type | |
93 | */ | |
c5e94482 | 94 | typedef enum { |
22a2d3d5 UG |
95 | GIT_CONFIGMAP_FALSE = 0, |
96 | GIT_CONFIGMAP_TRUE = 1, | |
97 | GIT_CONFIGMAP_INT32, | |
98 | GIT_CONFIGMAP_STRING | |
99 | } git_configmap_t; | |
c5e94482 | 100 | |
a295bd2d CMN |
101 | /** |
102 | * Mapping from config variables to values. | |
103 | */ | |
c5e94482 | 104 | typedef struct { |
22a2d3d5 | 105 | git_configmap_t type; |
c5e94482 VM |
106 | const char *str_match; |
107 | int map_value; | |
22a2d3d5 | 108 | } git_configmap; |
c5e94482 | 109 | |
19cb6857 VM |
110 | /** |
111 | * Locate the path to the global configuration file | |
112 | * | |
113 | * The user or global configuration file is usually | |
114 | * located in `$HOME/.gitconfig`. | |
115 | * | |
116 | * This method will try to guess the full path to that | |
117 | * file, if the file exists. The returned path | |
118 | * may be used on any `git_config` call to load the | |
119 | * global configuration file. | |
120 | * | |
4258d483 | 121 | * This method will not guess the path to the xdg compatible |
8b4f9b17 SS |
122 | * config file (.config/git/config). |
123 | * | |
ee550477 CMN |
124 | * @param out Pointer to a user-allocated git_buf in which to store the path |
125 | * @return 0 if a global configuration file has been found. Its path will be stored in `out`. | |
19cb6857 | 126 | */ |
ee550477 | 127 | GIT_EXTERN(int) git_config_find_global(git_buf *out); |
19cb6857 | 128 | |
8b4f9b17 | 129 | /** |
4258d483 | 130 | * Locate the path to the global xdg compatible configuration file |
8b4f9b17 | 131 | * |
4258d483 | 132 | * The xdg compatible configuration file is usually |
8b4f9b17 SS |
133 | * located in `$HOME/.config/git/config`. |
134 | * | |
135 | * This method will try to guess the full path to that | |
136 | * file, if the file exists. The returned path | |
137 | * may be used on any `git_config` call to load the | |
4258d483 | 138 | * xdg compatible configuration file. |
8b4f9b17 | 139 | * |
ee550477 | 140 | * @param out Pointer to a user-allocated git_buf in which to store the path |
4258d483 | 141 | * @return 0 if a xdg compatible configuration file has been |
ee550477 | 142 | * found. Its path will be stored in `out`. |
8b4f9b17 | 143 | */ |
ee550477 | 144 | GIT_EXTERN(int) git_config_find_xdg(git_buf *out); |
8b4f9b17 | 145 | |
4c562347 CMN |
146 | /** |
147 | * Locate the path to the system configuration file | |
148 | * | |
149 | * If /etc/gitconfig doesn't exist, it will look for | |
150 | * %PROGRAMFILES%\Git\etc\gitconfig. | |
ee550477 CMN |
151 | * |
152 | * @param out Pointer to a user-allocated git_buf in which to store the path | |
e172cf08 | 153 | * @return 0 if a system configuration file has been |
ee550477 | 154 | * found. Its path will be stored in `out`. |
4c562347 | 155 | */ |
ee550477 | 156 | GIT_EXTERN(int) git_config_find_system(git_buf *out); |
4c562347 | 157 | |
8c7c5fa5 CMN |
158 | /** |
159 | * Locate the path to the configuration file in ProgramData | |
160 | * | |
161 | * Look for the file in %PROGRAMDATA%\Git\config used by portable git. | |
162 | * | |
163 | * @param out Pointer to a user-allocated git_buf in which to store the path | |
164 | * @return 0 if a ProgramData configuration file has been | |
165 | * found. Its path will be stored in `out`. | |
166 | */ | |
167 | GIT_EXTERN(int) git_config_find_programdata(git_buf *out); | |
168 | ||
ca1b6e54 | 169 | /** |
a1abe66a | 170 | * Open the global, XDG and system configuration files |
ca1b6e54 | 171 | * |
a1abe66a | 172 | * Utility wrapper that finds the global, XDG and system configuration files |
ca1b6e54 | 173 | * and opens them into a single prioritized config object that can be |
85bd1746 | 174 | * used when accessing default config data outside a repository. |
ca1b6e54 RB |
175 | * |
176 | * @param out Pointer to store the config instance | |
177 | * @return 0 or an error code | |
178 | */ | |
85bd1746 | 179 | GIT_EXTERN(int) git_config_open_default(git_config **out); |
ca1b6e54 | 180 | |
c0335005 | 181 | /** |
a2a305fc CMN |
182 | * Allocate a new configuration object |
183 | * | |
184 | * This object is empty, so you have to add a file to it before you | |
185 | * can do anything with it. | |
186 | * | |
187 | * @param out pointer to the new configuration | |
e172cf08 | 188 | * @return 0 or an error code |
c0335005 CMN |
189 | */ |
190 | GIT_EXTERN(int) git_config_new(git_config **out); | |
191 | ||
c0335005 | 192 | /** |
07ff8817 VM |
193 | * Add an on-disk config file instance to an existing config |
194 | * | |
195 | * The on-disk file pointed at by `path` will be opened and | |
196 | * parsed; it's expected to be a native Git config file following | |
197 | * the default Git config syntax (see man git-config). | |
c0335005 | 198 | * |
1cef6b9f CMN |
199 | * If the file does not exist, the file will still be added and it |
200 | * will be created the first time we write to it. | |
201 | * | |
a2a305fc CMN |
202 | * Note that the configuration object will free the file |
203 | * automatically. | |
f44cbec4 | 204 | * |
07ff8817 VM |
205 | * Further queries on this config object will access each |
206 | * of the config file instances in order (instances with | |
a1abe66a | 207 | * a higher priority level will be accessed first). |
07ff8817 | 208 | * |
ce78f39e | 209 | * @param cfg the configuration to add the file to |
83041c71 | 210 | * @param path path to the configuration file to add |
a1abe66a | 211 | * @param level the priority level of the backend |
83041c71 | 212 | * @param force replace config file at the given priority level |
eae0bfdc PP |
213 | * @param repo optional repository to allow parsing of |
214 | * conditional includes | |
a1abe66a | 215 | * @return 0 on success, GIT_EEXISTS when adding more than one file |
270160b9 | 216 | * for a given priority level (and force_replace set to 0), |
217 | * GIT_ENOTFOUND when the file doesn't exist or error code | |
c0335005 | 218 | */ |
a1abe66a | 219 | GIT_EXTERN(int) git_config_add_file_ondisk( |
220 | git_config *cfg, | |
221 | const char *path, | |
16adc9fa | 222 | git_config_level_t level, |
eae0bfdc | 223 | const git_repository *repo, |
a1abe66a | 224 | int force); |
07ff8817 | 225 | |
07ff8817 VM |
226 | /** |
227 | * Create a new config instance containing a single on-disk file | |
228 | * | |
229 | * This method is a simple utility wrapper for the following sequence | |
230 | * of calls: | |
231 | * - git_config_new | |
232 | * - git_config_add_file_ondisk | |
233 | * | |
270160b9 | 234 | * @param out The configuration instance to create |
07ff8817 | 235 | * @param path Path to the on-disk file to open |
1cef6b9f | 236 | * @return 0 on success, or an error code |
07ff8817 | 237 | */ |
270160b9 | 238 | GIT_EXTERN(int) git_config_open_ondisk(git_config **out, const char *path); |
5d4cd003 | 239 | |
a1abe66a | 240 | /** |
241 | * Build a single-level focused config object from a multi-level one. | |
242 | * | |
243 | * The returned config object can be used to perform get/set/delete operations | |
244 | * on a single specific level. | |
245 | * | |
246 | * Getting several times the same level from the same parent multi-level config | |
247 | * will return different config instances, but containing the same config_file | |
248 | * instance. | |
249 | * | |
54b2a37a BS |
250 | * @param out The configuration instance to create |
251 | * @param parent Multi-level config to search for the given level | |
252 | * @param level Configuration level to search for | |
a1abe66a | 253 | * @return 0, GIT_ENOTFOUND if the passed level cannot be found in the |
254 | * multi-level parent config, or an error code | |
255 | */ | |
256 | GIT_EXTERN(int) git_config_open_level( | |
0cb16fe9 L |
257 | git_config **out, |
258 | const git_config *parent, | |
16adc9fa | 259 | git_config_level_t level); |
a1abe66a | 260 | |
5d831887 CMN |
261 | /** |
262 | * Open the global/XDG configuration file according to git's rules | |
263 | * | |
264 | * Git allows you to store your global configuration at | |
ac3d33df | 265 | * `$HOME/.gitconfig` or `$XDG_CONFIG_HOME/git/config`. For backwards |
5d831887 CMN |
266 | * compatability, the XDG file shouldn't be used unless the use has |
267 | * created it explicitly. With this function you'll open the correct | |
268 | * one to write to. | |
269 | * | |
270 | * @param out pointer in which to store the config object | |
271 | * @param config the config object in which to look | |
272 | */ | |
273 | GIT_EXTERN(int) git_config_open_global(git_config **out, git_config *config); | |
274 | ||
55ebd7d3 CMN |
275 | /** |
276 | * Create a snapshot of the configuration | |
277 | * | |
278 | * Create a snapshot of the current state of a configuration, which | |
279 | * allows you to look into a consistent view of the configuration for | |
280 | * looking up complex values (e.g. a remote, submodule). | |
281 | * | |
c20d71ea CMN |
282 | * The string returned when querying such a config object is valid |
283 | * until it is freed. | |
284 | * | |
55ebd7d3 CMN |
285 | * @param out pointer in which to store the snapshot config object |
286 | * @param config configuration to snapshot | |
287 | * @return 0 or an error code | |
288 | */ | |
289 | GIT_EXTERN(int) git_config_snapshot(git_config **out, git_config *config); | |
290 | ||
5d4cd003 | 291 | /** |
a2a305fc | 292 | * Free the configuration and its associated memory and files |
9a3c5e55 CMN |
293 | * |
294 | * @param cfg the configuration to free | |
5d4cd003 CMN |
295 | */ |
296 | GIT_EXTERN(void) git_config_free(git_config *cfg); | |
297 | ||
a1abe66a | 298 | /** |
299 | * Get the git_config_entry of a config variable. | |
300 | * | |
9a97f49e CMN |
301 | * Free the git_config_entry after use with `git_config_entry_free()`. |
302 | * | |
a1abe66a | 303 | * @param out pointer to the variable git_config_entry |
304 | * @param cfg where to look for the variable | |
305 | * @param name the variable's name | |
306 | * @return 0 or an error code | |
307 | */ | |
54b2a37a | 308 | GIT_EXTERN(int) git_config_get_entry( |
9a97f49e | 309 | git_config_entry **out, |
54b2a37a BS |
310 | const git_config *cfg, |
311 | const char *name); | |
a1abe66a | 312 | |
9a3c5e55 CMN |
313 | /** |
314 | * Get the value of an integer config variable. | |
315 | * | |
a1abe66a | 316 | * All config files will be looked into, in the order of their |
317 | * defined level. A higher level means a higher priority. The | |
b874629b | 318 | * first occurrence of the variable will be returned here. |
a1abe66a | 319 | * |
29e948de | 320 | * @param out pointer to the variable where the value should be stored |
9a3c5e55 CMN |
321 | * @param cfg where to look for the variable |
322 | * @param name the variable's name | |
e172cf08 | 323 | * @return 0 or an error code |
9a3c5e55 | 324 | */ |
54b2a37a | 325 | GIT_EXTERN(int) git_config_get_int32(int32_t *out, const git_config *cfg, const char *name); |
9a3c5e55 | 326 | |
e69ac243 CMN |
327 | /** |
328 | * Get the value of a long integer config variable. | |
329 | * | |
a1abe66a | 330 | * All config files will be looked into, in the order of their |
331 | * defined level. A higher level means a higher priority. The | |
7eb222fc | 332 | * first occurrence of the variable will be returned here. |
a1abe66a | 333 | * |
29e948de | 334 | * @param out pointer to the variable where the value should be stored |
e69ac243 CMN |
335 | * @param cfg where to look for the variable |
336 | * @param name the variable's name | |
e172cf08 | 337 | * @return 0 or an error code |
e69ac243 | 338 | */ |
54b2a37a | 339 | GIT_EXTERN(int) git_config_get_int64(int64_t *out, const git_config *cfg, const char *name); |
e69ac243 | 340 | |
9a3c5e55 CMN |
341 | /** |
342 | * Get the value of a boolean config variable. | |
343 | * | |
2974aa94 CMN |
344 | * This function uses the usual C convention of 0 being false and |
345 | * anything else true. | |
346 | * | |
a1abe66a | 347 | * All config files will be looked into, in the order of their |
348 | * defined level. A higher level means a higher priority. The | |
7eb222fc | 349 | * first occurrence of the variable will be returned here. |
a1abe66a | 350 | * |
29e948de | 351 | * @param out pointer to the variable where the value should be stored |
9a3c5e55 CMN |
352 | * @param cfg where to look for the variable |
353 | * @param name the variable's name | |
e172cf08 | 354 | * @return 0 or an error code |
9a3c5e55 | 355 | */ |
54b2a37a | 356 | GIT_EXTERN(int) git_config_get_bool(int *out, const git_config *cfg, const char *name); |
9a3c5e55 | 357 | |
eac773d9 CMN |
358 | /** |
359 | * Get the value of a path config variable. | |
360 | * | |
361 | * A leading '~' will be expanded to the global search path (which | |
362 | * defaults to the user's home directory but can be overridden via | |
363 | * `git_libgit2_opts()`. | |
364 | * | |
365 | * All config files will be looked into, in the order of their | |
366 | * defined level. A higher level means a higher priority. The | |
367 | * first occurrence of the variable will be returned here. | |
368 | * | |
369 | * @param out the buffer in which to store the result | |
370 | * @param cfg where to look for the variable | |
371 | * @param name the variable's name | |
ec7e1c93 | 372 | * @return 0 or an error code |
eac773d9 CMN |
373 | */ |
374 | GIT_EXTERN(int) git_config_get_path(git_buf *out, const git_config *cfg, const char *name); | |
375 | ||
9a3c5e55 CMN |
376 | /** |
377 | * Get the value of a string config variable. | |
378 | * | |
9a97f49e CMN |
379 | * This function can only be used on snapshot config objects. The |
380 | * string is owned by the config and should not be freed by the | |
381 | * user. The pointer will be valid until the config is freed. | |
9a3c5e55 | 382 | * |
a1abe66a | 383 | * All config files will be looked into, in the order of their |
384 | * defined level. A higher level means a higher priority. The | |
7eb222fc | 385 | * first occurrence of the variable will be returned here. |
a1abe66a | 386 | * |
9a97f49e | 387 | * @param out pointer to the string |
9a3c5e55 CMN |
388 | * @param cfg where to look for the variable |
389 | * @param name the variable's name | |
e172cf08 | 390 | * @return 0 or an error code |
9a3c5e55 | 391 | */ |
54b2a37a | 392 | GIT_EXTERN(int) git_config_get_string(const char **out, const git_config *cfg, const char *name); |
9a3c5e55 | 393 | |
9a97f49e CMN |
394 | /** |
395 | * Get the value of a string config variable. | |
396 | * | |
397 | * The value of the config will be copied into the buffer. | |
398 | * | |
399 | * All config files will be looked into, in the order of their | |
400 | * defined level. A higher level means a higher priority. The | |
401 | * first occurrence of the variable will be returned here. | |
402 | * | |
403 | * @param out buffer in which to store the string | |
404 | * @param cfg where to look for the variable | |
405 | * @param name the variable's name | |
406 | * @return 0 or an error code | |
407 | */ | |
408 | GIT_EXTERN(int) git_config_get_string_buf(git_buf *out, const git_config *cfg, const char *name); | |
409 | ||
5e0dc4af | 410 | /** |
4efa3290 | 411 | * Get each value of a multivar in a foreach callback |
d9da4cca CMN |
412 | * |
413 | * The callback will be called on each variable found | |
414 | * | |
eae0bfdc PP |
415 | * The regular expression is applied case-sensitively on the normalized form of |
416 | * the variable name: the section and variable parts are lower-cased. The | |
417 | * subsection is left unchanged. | |
418 | * | |
d9da4cca CMN |
419 | * @param cfg where to look for the variable |
420 | * @param name the variable's name | |
421 | * @param regexp regular expression to filter which variables we're | |
422 | * interested in. Use NULL to indicate all | |
e1967164 AL |
423 | * @param callback the function to be called on each value of the variable |
424 | * @param payload opaque pointer to pass to the callback | |
5e0dc4af | 425 | */ |
4efa3290 | 426 | GIT_EXTERN(int) git_config_get_multivar_foreach(const git_config *cfg, const char *name, const char *regexp, git_config_foreach_cb callback, void *payload); |
5e0dc4af | 427 | |
99dfb538 CMN |
428 | /** |
429 | * Get each value of a multivar | |
430 | * | |
eae0bfdc PP |
431 | * The regular expression is applied case-sensitively on the normalized form of |
432 | * the variable name: the section and variable parts are lower-cased. The | |
433 | * subsection is left unchanged. | |
434 | * | |
99dfb538 CMN |
435 | * @param out pointer to store the iterator |
436 | * @param cfg where to look for the variable | |
437 | * @param name the variable's name | |
438 | * @param regexp regular expression to filter which variables we're | |
439 | * interested in. Use NULL to indicate all | |
440 | */ | |
f4be8209 | 441 | GIT_EXTERN(int) git_config_multivar_iterator_new(git_config_iterator **out, const git_config *cfg, const char *name, const char *regexp); |
1e96c9d5 CMN |
442 | |
443 | /** | |
444 | * Return the current entry and advance the iterator | |
445 | * | |
c20d71ea CMN |
446 | * The pointers returned by this function are valid until the iterator |
447 | * is freed. | |
448 | * | |
1e96c9d5 CMN |
449 | * @param entry pointer to store the entry |
450 | * @param iter the iterator | |
451 | * @return 0 or an error code. GIT_ITEROVER if the iteration has completed | |
452 | */ | |
453 | GIT_EXTERN(int) git_config_next(git_config_entry **entry, git_config_iterator *iter); | |
454 | ||
455 | /** | |
456 | * Free a config iterator | |
457 | * | |
458 | * @param iter the iterator to free | |
459 | */ | |
460 | GIT_EXTERN(void) git_config_iterator_free(git_config_iterator *iter); | |
461 | ||
9a3c5e55 | 462 | /** |
a1abe66a | 463 | * Set the value of an integer config variable in the config file |
464 | * with the highest level (usually the local one). | |
9a3c5e55 CMN |
465 | * |
466 | * @param cfg where to look for the variable | |
467 | * @param name the variable's name | |
d144c569 | 468 | * @param value Integer value for the variable |
e172cf08 | 469 | * @return 0 or an error code |
9a3c5e55 | 470 | */ |
fafd4710 | 471 | GIT_EXTERN(int) git_config_set_int32(git_config *cfg, const char *name, int32_t value); |
9a3c5e55 | 472 | |
e69ac243 | 473 | /** |
a1abe66a | 474 | * Set the value of a long integer config variable in the config file |
475 | * with the highest level (usually the local one). | |
e69ac243 CMN |
476 | * |
477 | * @param cfg where to look for the variable | |
478 | * @param name the variable's name | |
d144c569 | 479 | * @param value Long integer value for the variable |
e172cf08 | 480 | * @return 0 or an error code |
e69ac243 | 481 | */ |
fafd4710 | 482 | GIT_EXTERN(int) git_config_set_int64(git_config *cfg, const char *name, int64_t value); |
e69ac243 | 483 | |
9a3c5e55 | 484 | /** |
a1abe66a | 485 | * Set the value of a boolean config variable in the config file |
486 | * with the highest level (usually the local one). | |
9a3c5e55 CMN |
487 | * |
488 | * @param cfg where to look for the variable | |
489 | * @param name the variable's name | |
490 | * @param value the value to store | |
e172cf08 | 491 | * @return 0 or an error code |
9a3c5e55 | 492 | */ |
2974aa94 | 493 | GIT_EXTERN(int) git_config_set_bool(git_config *cfg, const char *name, int value); |
9a3c5e55 CMN |
494 | |
495 | /** | |
a1abe66a | 496 | * Set the value of a string config variable in the config file |
497 | * with the highest level (usually the local one). | |
9a3c5e55 CMN |
498 | * |
499 | * A copy of the string is made and the user is free to use it | |
500 | * afterwards. | |
501 | * | |
502 | * @param cfg where to look for the variable | |
503 | * @param name the variable's name | |
504 | * @param value the string to store. | |
e172cf08 | 505 | * @return 0 or an error code |
9a3c5e55 CMN |
506 | */ |
507 | GIT_EXTERN(int) git_config_set_string(git_config *cfg, const char *name, const char *value); | |
508 | ||
3005855f | 509 | /** |
a1abe66a | 510 | * Set a multivar in the local config file. |
d9da4cca | 511 | * |
eae0bfdc PP |
512 | * The regular expression is applied case-sensitively on the value. |
513 | * | |
d9da4cca CMN |
514 | * @param cfg where to look for the variable |
515 | * @param name the variable's name | |
516 | * @param regexp a regular expression to indicate which values to replace | |
517 | * @param value the new value. | |
3005855f CMN |
518 | */ |
519 | GIT_EXTERN(int) git_config_set_multivar(git_config *cfg, const char *name, const char *regexp, const char *value); | |
520 | ||
9a3c5e55 | 521 | /** |
a1abe66a | 522 | * Delete a config variable from the config file |
523 | * with the highest level (usually the local one). | |
2601fcfc CMN |
524 | * |
525 | * @param cfg the configuration | |
526 | * @param name the variable to delete | |
527 | */ | |
54b2a37a | 528 | GIT_EXTERN(int) git_config_delete_entry(git_config *cfg, const char *name); |
2601fcfc | 529 | |
3793fa9b DRT |
530 | /** |
531 | * Deletes one or several entries from a multivar in the local config file. | |
532 | * | |
eae0bfdc PP |
533 | * The regular expression is applied case-sensitively on the value. |
534 | * | |
3793fa9b DRT |
535 | * @param cfg where to look for the variables |
536 | * @param name the variable's name | |
537 | * @param regexp a regular expression to indicate which values to delete | |
538 | * | |
539 | * @return 0 or an error code | |
540 | */ | |
541 | GIT_EXTERN(int) git_config_delete_multivar(git_config *cfg, const char *name, const char *regexp); | |
542 | ||
2601fcfc CMN |
543 | /** |
544 | * Perform an operation on each config variable. | |
9a3c5e55 | 545 | * |
cfef5fb7 VM |
546 | * The callback receives the normalized name and value of each variable |
547 | * in the config backend, and the data pointer passed to this function. | |
373cf6a9 RB |
548 | * If the callback returns a non-zero value, the function stops iterating |
549 | * and returns that value to the caller. | |
9a3c5e55 | 550 | * |
c20d71ea CMN |
551 | * The pointers passed to the callback are only valid as long as the |
552 | * iteration is ongoing. | |
553 | * | |
9a3c5e55 CMN |
554 | * @param cfg where to get the variables from |
555 | * @param callback the function to call on each variable | |
e0fc39da | 556 | * @param payload the data to pass to the callback |
373cf6a9 | 557 | * @return 0 on success, non-zero callback return value, or error code |
9a3c5e55 | 558 | */ |
cfef5fb7 | 559 | GIT_EXTERN(int) git_config_foreach( |
54b2a37a BS |
560 | const git_config *cfg, |
561 | git_config_foreach_cb callback, | |
cfef5fb7 | 562 | void *payload); |
9a3c5e55 | 563 | |
5880962d CMN |
564 | /** |
565 | * Iterate over all the config variables | |
566 | * | |
567 | * Use `git_config_next` to advance the iteration and | |
568 | * `git_config_iterator_free` when done. | |
569 | * | |
570 | * @param out pointer to store the iterator | |
571 | * @param cfg where to ge the variables from | |
572 | */ | |
573 | GIT_EXTERN(int) git_config_iterator_new(git_config_iterator **out, const git_config *cfg); | |
574 | ||
54f3a572 CMN |
575 | /** |
576 | * Iterate over all the config variables whose name matches a pattern | |
577 | * | |
578 | * Use `git_config_next` to advance the iteration and | |
579 | * `git_config_iterator_free` when done. | |
580 | * | |
eae0bfdc PP |
581 | * The regular expression is applied case-sensitively on the normalized form of |
582 | * the variable name: the section and variable parts are lower-cased. The | |
583 | * subsection is left unchanged. | |
584 | * | |
54f3a572 CMN |
585 | * @param out pointer to store the iterator |
586 | * @param cfg where to ge the variables from | |
587 | * @param regexp regular expression to match the names | |
588 | */ | |
589 | GIT_EXTERN(int) git_config_iterator_glob_new(git_config_iterator **out, const git_config *cfg, const char *regexp); | |
590 | ||
b3ff1dab RB |
591 | /** |
592 | * Perform an operation on each config variable matching a regular expression. | |
593 | * | |
ac3d33df | 594 | * This behaves like `git_config_foreach` with an additional filter of a |
b3ff1dab RB |
595 | * regular expression that filters which config keys are passed to the |
596 | * callback. | |
597 | * | |
eae0bfdc PP |
598 | * The regular expression is applied case-sensitively on the normalized form of |
599 | * the variable name: the section and variable parts are lower-cased. The | |
600 | * subsection is left unchanged. | |
601 | * | |
602 | * The regular expression is applied case-sensitively on the normalized form of | |
603 | * the variable name: the case-insensitive parts are lower-case. | |
c20d71ea | 604 | * |
b3ff1dab RB |
605 | * @param cfg where to get the variables from |
606 | * @param regexp regular expression to match against config names | |
607 | * @param callback the function to call on each variable | |
608 | * @param payload the data to pass to the callback | |
609 | * @return 0 or the return value of the callback which didn't return 0 | |
610 | */ | |
611 | GIT_EXTERN(int) git_config_foreach_match( | |
54b2a37a | 612 | const git_config *cfg, |
b3ff1dab | 613 | const char *regexp, |
54b2a37a | 614 | git_config_foreach_cb callback, |
b3ff1dab | 615 | void *payload); |
c5e94482 VM |
616 | |
617 | /** | |
618 | * Query the value of a config variable and return it mapped to | |
619 | * an integer constant. | |
620 | * | |
621 | * This is a helper method to easily map different possible values | |
622 | * to a variable to integer constants that easily identify them. | |
623 | * | |
624 | * A mapping array looks as follows: | |
625 | * | |
22a2d3d5 | 626 | * git_configmap autocrlf_mapping[] = { |
c5e94482 VM |
627 | * {GIT_CVAR_FALSE, NULL, GIT_AUTO_CRLF_FALSE}, |
628 | * {GIT_CVAR_TRUE, NULL, GIT_AUTO_CRLF_TRUE}, | |
629 | * {GIT_CVAR_STRING, "input", GIT_AUTO_CRLF_INPUT}, | |
630 | * {GIT_CVAR_STRING, "default", GIT_AUTO_CRLF_DEFAULT}}; | |
631 | * | |
632 | * On any "false" value for the variable (e.g. "false", "FALSE", "no"), the | |
633 | * mapping will store `GIT_AUTO_CRLF_FALSE` in the `out` parameter. | |
634 | * | |
635 | * The same thing applies for any "true" value such as "true", "yes" or "1", storing | |
636 | * the `GIT_AUTO_CRLF_TRUE` variable. | |
637 | * | |
638 | * Otherwise, if the value matches the string "input" (with case insensitive comparison), | |
639 | * the given constant will be stored in `out`, and likewise for "default". | |
640 | * | |
641 | * If not a single match can be made to store in `out`, an error code will be | |
642 | * returned. | |
643 | * | |
29e948de | 644 | * @param out place to store the result of the mapping |
c5e94482 VM |
645 | * @param cfg config file to get the variables from |
646 | * @param name name of the config variable to lookup | |
22a2d3d5 | 647 | * @param maps array of `git_configmap` objects specifying the possible mappings |
c5e94482 | 648 | * @param map_n number of mapping objects in `maps` |
e172cf08 | 649 | * @return 0 on success, error code otherwise |
c5e94482 | 650 | */ |
54b2a37a | 651 | GIT_EXTERN(int) git_config_get_mapped( |
0cb16fe9 L |
652 | int *out, |
653 | const git_config *cfg, | |
654 | const char *name, | |
22a2d3d5 | 655 | const git_configmap *maps, |
0cb16fe9 | 656 | size_t map_n); |
c5e94482 | 657 | |
a1abe66a | 658 | /** |
659 | * Maps a string value to an integer constant | |
660 | * | |
661 | * @param out place to store the result of the parsing | |
22a2d3d5 | 662 | * @param maps array of `git_configmap` objects specifying the possible mappings |
a1abe66a | 663 | * @param map_n number of mapping objects in `maps` |
664 | * @param value value to parse | |
665 | */ | |
666 | GIT_EXTERN(int) git_config_lookup_map_value( | |
667 | int *out, | |
22a2d3d5 | 668 | const git_configmap *maps, |
a1abe66a | 669 | size_t map_n, |
670 | const char *value); | |
671 | ||
672 | /** | |
673 | * Parse a string value as a bool. | |
674 | * | |
675 | * Valid values for true are: 'true', 'yes', 'on', 1 or any | |
676 | * number different from 0 | |
677 | * Valid values for false are: 'false', 'no', 'off', 0 | |
678 | * | |
679 | * @param out place to store the result of the parsing | |
680 | * @param value value to parse | |
681 | */ | |
682 | GIT_EXTERN(int) git_config_parse_bool(int *out, const char *value); | |
683 | ||
684 | /** | |
54b2a37a | 685 | * Parse a string value as an int32. |
a1abe66a | 686 | * |
687 | * An optional value suffix of 'k', 'm', or 'g' will | |
688 | * cause the value to be multiplied by 1024, 1048576, | |
689 | * or 1073741824 prior to output. | |
690 | * | |
691 | * @param out place to store the result of the parsing | |
692 | * @param value value to parse | |
693 | */ | |
54b2a37a | 694 | GIT_EXTERN(int) git_config_parse_int32(int32_t *out, const char *value); |
a1abe66a | 695 | |
696 | /** | |
54b2a37a | 697 | * Parse a string value as an int64. |
a1abe66a | 698 | * |
699 | * An optional value suffix of 'k', 'm', or 'g' will | |
700 | * cause the value to be multiplied by 1024, 1048576, | |
701 | * or 1073741824 prior to output. | |
702 | * | |
703 | * @param out place to store the result of the parsing | |
704 | * @param value value to parse | |
705 | */ | |
54b2a37a | 706 | GIT_EXTERN(int) git_config_parse_int64(int64_t *out, const char *value); |
a1abe66a | 707 | |
eac773d9 CMN |
708 | /** |
709 | * Parse a string value as a path. | |
710 | * | |
711 | * A leading '~' will be expanded to the global search path (which | |
712 | * defaults to the user's home directory but can be overridden via | |
713 | * `git_libgit2_opts()`. | |
714 | * | |
715 | * If the value does not begin with a tilde, the input will be | |
716 | * returned. | |
717 | * | |
718 | * @param out placae to store the result of parsing | |
719 | * @param value the path to evaluate | |
720 | */ | |
721 | GIT_EXTERN(int) git_config_parse_path(git_buf *out, const char *value); | |
a1abe66a | 722 | |
a603c191 | 723 | /** |
ac3d33df | 724 | * Perform an operation on each config variable in a given config backend, |
a603c191 NG |
725 | * matching a regular expression. |
726 | * | |
ac3d33df JK |
727 | * This behaves like `git_config_foreach_match` except that only config |
728 | * entries from the given backend entry are enumerated. | |
a603c191 | 729 | * |
eae0bfdc PP |
730 | * The regular expression is applied case-sensitively on the normalized form of |
731 | * the variable name: the section and variable parts are lower-cased. The | |
732 | * subsection is left unchanged. | |
733 | * | |
a603c191 NG |
734 | * @param backend where to get the variables from |
735 | * @param regexp regular expression to match against config names (can be NULL) | |
736 | * @param callback the function to call on each variable | |
737 | * @param payload the data to pass to the callback | |
738 | */ | |
739 | GIT_EXTERN(int) git_config_backend_foreach_match( | |
740 | git_config_backend *backend, | |
741 | const char *regexp, | |
25e0b157 RB |
742 | git_config_foreach_cb callback, |
743 | void *payload); | |
a603c191 NG |
744 | |
745 | ||
36f784b5 CMN |
746 | /** |
747 | * Lock the backend with the highest priority | |
748 | * | |
749 | * Locking disallows anybody else from writing to that backend. Any | |
750 | * updates made after locking will not be visible to a reader until | |
751 | * the file is unlocked. | |
752 | * | |
5340d63d CMN |
753 | * You can apply the changes by calling `git_transaction_commit()` |
754 | * before freeing the transaction. Either of these actions will unlock | |
755 | * the config. | |
36f784b5 | 756 | * |
5340d63d CMN |
757 | * @param tx the resulting transaction, use this to commit or undo the |
758 | * changes | |
759 | * @param cfg the configuration in which to lock | |
36f784b5 CMN |
760 | * @return 0 or an error code |
761 | */ | |
5340d63d | 762 | GIT_EXTERN(int) git_config_lock(git_transaction **tx, git_config *cfg); |
36f784b5 | 763 | |
5d4cd003 CMN |
764 | /** @} */ |
765 | GIT_END_DECL | |
766 | #endif |