| blob | cbb0f4fddcddec73ef61c65f8e9e88e496bc69dc |
1 #ifndef CONFIG_H
2 #define CONFIG_H
9 /**
10 * The config API gives callers a way to access Git configuration files
11 * (and files which have the same syntax).
12 *
13 * General Usage
14 * -------------
15 *
16 * Config files are parsed linearly, and each variable found is passed to a
17 * caller-provided callback function. The callback function is responsible
18 * for any actions to be taken on the config option, and is free to ignore
19 * some options. It is not uncommon for the configuration to be parsed
20 * several times during the run of a Git program, with different callbacks
21 * picking out different variables useful to themselves.
22 */
26 /* git_config_parse_key() returns these negated: */
27 #define CONFIG_INVALID_KEY 1
28 #define CONFIG_NO_SECTION_OR_NAME 2
29 /* repo_config_set_gently(), repo_config_set_multivar_gently() return the above or these: */
30 #define CONFIG_NO_LOCK -1
31 #define CONFIG_INVALID_FILE 3
32 #define CONFIG_NO_WRITE 4
33 #define CONFIG_NOTHING_SET 5
34 #define CONFIG_INVALID_PATTERN 6
35 #define CONFIG_GENERIC_ERROR 7
37 #define CONFIG_REGEX_NONE ((void *)1)
41 CONFIG_SCOPE_SYSTEM,
42 CONFIG_SCOPE_GLOBAL,
43 CONFIG_SCOPE_LOCAL,
44 CONFIG_SCOPE_WORKTREE,
45 CONFIG_SCOPE_COMMAND,
46 CONFIG_SCOPE_SUBMODULE,
47 };
55 };
59 CONFIG_ORIGIN_BLOB,
60 CONFIG_ORIGIN_FILE,
61 CONFIG_ORIGIN_STDIN,
62 CONFIG_ORIGIN_SUBMODULE_BLOB,
63 CONFIG_ORIGIN_CMDLINE
64 };
67 CONFIG_EVENT_SECTION,
68 CONFIG_EVENT_ENTRY,
69 CONFIG_EVENT_WHITESPACE,
70 CONFIG_EVENT_COMMENT,
71 CONFIG_EVENT_EOF,
72 CONFIG_EVENT_ERROR
73 };
76 /*
77 * The parser event function (if not NULL) is called with the event type and
78 * the begin/end offsets of the parsed elements.
79 *
80 * Note: for CONFIG_EVENT_ENTRY (i.e. config variables), the trailing newline
81 * character is considered part of the element.
82 */
95 /*
96 * For internal use. Include all includeif.hasremoteurl paths without
97 * checking if the repo has that remote URL, and when doing so, verify
98 * that files included in this way do not configure any remote URLs
99 * themselves.
100 */
105 /*
106 * event_fn and event_fn_data are for internal use only. Handles events
107 * emitted by the config parser.
108 */
109 config_parser_event_fn_t event_fn;
117 };
119 /* Config source metadata for a given config key-value pair */
125 };
126 #define KVI_INIT { \
127 .filename = NULL, \
128 .linenr = -1, \
129 .origin_type = CONFIG_ORIGIN_UNKNOWN, \
130 .scope = CONFIG_SCOPE_UNKNOWN, \
131 }
133 /* Captures additional information that a config callback can use. */
135 /* Config source metadata for key and value. */
137 };
138 #define CONFIG_CONTEXT_INIT { 0 }
140 /**
141 * A config callback function takes four parameters:
142 *
143 * - the name of the parsed variable. This is in canonical "flat" form: the
144 * section, subsection, and variable segments will be separated by dots,
145 * and the section and variable segments will be all lowercase. E.g.,
146 * `core.ignorecase`, `diff.SomeType.textconv`.
147 *
148 * - the value of the found variable, as a string. If the variable had no
149 * value specified, the value will be NULL (typically this means it
150 * should be interpreted as boolean true).
151 *
152 * - the 'config context', that is, additional information about the config
153 * iteration operation provided by the config machinery. For example, this
154 * includes information about the config source being parsed (e.g. the
155 * filename).
156 *
157 * - a void pointer passed in by the caller of the config API; this can
158 * contain callback-specific data
159 *
160 * A config callback should return 0 for success, or -1 if the variable
161 * could not be parsed properly.
162 */
169 /**
170 * Read a specific file in git-config format.
171 * This function takes the same callback and data parameters as `repo_config`.
172 *
173 * Unlike repo_config(), this function does not respect includes.
174 */
194 /*
195 * Read config when the Git directory has not yet been set up. In case
196 * `the_repository` has not yet been set up, try to discover the Git
197 * directory to read the configuration from.
198 */
201 /*
202 * Read config but only enumerate system and global settings.
203 * Omit any repo-local, worktree-local, or command-line settings.
204 */
207 /**
208 * Most programs will simply want to look up variables in all config files
209 * that Git knows about, using the normal precedence rules. To do this,
210 * call `repo_config` with a callback function and void data pointer.
211 *
212 * `repo_config` will read all config sources in order of increasing
213 * priority. Thus a callback should typically overwrite previously-seen
214 * entries with new ones (e.g., if both the user-wide `~/.gitconfig` and
215 * repo-specific `.git/config` contain `color.ui`, the config machinery
216 * will first feed the user-wide one to the callback, and then the
217 * repo-specific one; by overwriting, the higher-priority repo-specific
218 * value is left at the end).
219 *
220 * In cases where the repository variable is NULL, repo_config() will
221 * skip the per-repository config but retain system and global configs
222 * by calling read_very_early_config() which also ignores one-time
223 * overrides like "git -c var=val". This is to support handling "git foo -h"
224 * (which lets git.c:run_builtin() to pass NULL and have the cmd_foo()
225 * call repo_config() before calling parse_options() to notice "-h", give
226 * help and exit) for a command that ordinarily require a repository
227 * so this limitation may be OK (but if needed you are welcome to fix it).
228 *
229 * Unlike git_config_from_file(), this function respects includes.
230 */
233 /**
234 * Lets the caller examine config while adjusting some of the default
235 * behavior of `repo_config`. It should almost never be used by "regular"
236 * Git code that is looking up configuration variables.
237 * It is intended for advanced callers like `git-config`, which are
238 * intentionally tweaking the normal config-lookup process.
239 * It takes two extra parameters:
240 *
241 * - `config_source`
242 * If this parameter is non-NULL, it specifies the source to parse for
243 * configuration, rather than looking in the usual files. See `struct
244 * git_config_source` in `config.h` for details. Regular `repo_config` defaults
245 * to `NULL`.
246 *
247 * - `opts`
248 * Specify options to adjust the behavior of parsing config files. See `struct
249 * config_options` in `config.h` for details. As an example: regular `repo_config`
250 * sets `opts.respect_includes` to `1` by default.
251 */
257 /**
258 * Value Parsing Helpers
259 * ---------------------
260 *
261 * The following helper functions aid in parsing string values
262 */
264 /**
265 * Parse the string to an integer, including unit factors. Dies on error;
266 * otherwise, returns the parsed result.
267 */
273 /**
274 * Identical to `git_config_int`, but for unsigned longs.
275 */
282 /**
283 * Identically to `git_config_double`, but for double-precision floating point
284 * values.
285 */
289 /**
290 * Same as `git_config_bool`, except that integers are returned as-is, and
291 * an `is_bool` flag is unset.
292 */
296 /**
297 * Parse a string into a boolean value, respecting keywords like "true" and
298 * "false". Integer values are converted into true/false values (when they
299 * are non-zero or zero, respectively). Other values cause a die(). If
300 * parsing is successful, the return value is the result.
301 */
304 /**
305 * Allocates and copies the value string into the `dest` parameter; if no
306 * string is given, prints an error message and returns -1.
307 */
310 /**
311 * Similar to `git_config_string`, but expands `~` or `~user` into the
312 * user's home directory when found at the beginning of the path.
313 */
321 /**
322 * write config values to a specific config file, takes a key/value pair as
323 * parameter.
324 */
329 /**
330 * Write a config value that should apply to the current worktree. If
331 * extensions.worktreeConfig is enabled, then the write will happen in the
332 * current worktree's config. Otherwise, write to the common config file.
333 */
336 /**
337 * write config values to `.git/config`, takes a key/value pair as parameter.
338 */
343 /*
344 * The following macros specify flag bits that alter the behavior
345 * of the repo_config_set_multivar*() methods.
346 */
348 /*
349 * When CONFIG_FLAGS_MULTI_REPLACE is specified, all matching key/values
350 * are removed before a single new pair is written. If the flag is not
351 * present, then set operations replace only the first match.
352 */
353 #define CONFIG_FLAGS_MULTI_REPLACE (1 << 0)
355 /*
356 * When CONFIG_FLAGS_FIXED_VALUE is specified, match key/value pairs
357 * by string comparison (not regex match) to the provided value_pattern
358 * parameter.
359 */
360 #define CONFIG_FLAGS_FIXED_VALUE (1 << 1)
362 int repo_config_set_multivar_gently(struct repository *, const char *, const char *, const char *, unsigned);
363 void repo_config_set_multivar(struct repository *r, const char *, const char *, const char *, unsigned);
364 int repo_config_set_multivar_in_file_gently(struct repository *, const char *, const char *, const char *, const char *, const char *, unsigned);
368 /**
369 * takes four parameters:
370 *
371 * - the name of the file, as a string, to which key/value pairs will be written.
372 *
373 * - the name of key, as a string. This is in canonical "flat" form: the section,
374 * subsection, and variable segments will be separated by dots, and the section
375 * and variable segments will be all lowercase.
376 * E.g., `core.ignorecase`, `diff.SomeType.textconv`.
377 *
378 * - the value of the variable, as a string. If value is equal to NULL, it will
379 * remove the matching key from the config file.
380 *
381 * - the value regex, as a string. It will disregard key/value pairs where value
382 * does not match.
383 *
384 * - a flags value with bits corresponding to the CONFIG_FLAG_* macros.
385 *
386 * It returns 0 on success.
387 */
395 /**
396 * rename or remove sections in the config file
397 * parameters `old_name` and `new_name`
398 * If NULL is passed through `new_name` parameter,
399 * the section will be removed from the config file.
400 */
403 int repo_config_rename_section_in_file(struct repository *, const char *, const char *, const char *);
405 int repo_config_copy_section_in_file(struct repository *, const char *, const char *, const char *);
408 #if defined(__GNUC__)
409 #define config_error_nonbool(s) (config_error_nonbool(s), const_error())
410 #endif
421 /*
422 * Match and parse a config key of the form:
423 *
424 * section.(subsection.)?key
425 *
426 * (i.e., what gets handed to a config_fn_t). The caller provides the section;
427 * we return -1 if it does not match, 0 otherwise. The subsection and key
428 * out-parameters are filled by the function (and *subsection is NULL if it is
429 * missing).
430 *
431 * If the subsection pointer-to-pointer passed in is NULL, returns 0 only if
432 * there is no subsection at all.
433 */
439 /**
440 * Custom Configsets
441 * -----------------
442 *
443 * A `config_set` can be used to construct an in-memory cache for
444 * config-like files that the caller specifies (i.e., files like `.gitmodules`,
445 * `~/.gitconfig` etc.). For example,
446 *
447 * ----------------------------------------
448 * struct config_set gm_config;
449 * git_configset_init(&gm_config);
450 * int b;
451 * //we add config files to the config_set
452 * git_configset_add_file(&gm_config, ".gitmodules");
453 * git_configset_add_file(&gm_config, ".gitmodules_alt");
454 *
455 * if (!git_configset_get_bool(gm_config, "submodule.frotz.ignore", &b)) {
456 * //hack hack hack
457 * }
458 *
459 * when we are done with the configset:
460 * git_configset_clear(&gm_config);
461 * ----------------------------------------
462 *
463 * Configset API provides functions for the above mentioned work flow
464 */
470 };
475 };
477 /*
478 * the contents of the list are ordered according to their
479 * position in the config files and order of parsing the files.
480 * (i.e. key-value pair at the last position of .git/config will
481 * be at the last item of the list)
482 */
486 };
492 };
494 /**
495 * Initializes the config_set `cs`.
496 */
499 /**
500 * Parses the file and adds the variable-value pairs to the `config_set`,
501 * dies if there is an error in parsing the file. Returns 0 on success, or
502 * -1 if the file does not exist or is inaccessible. The caller decides
503 * whether to free the incomplete configset or continue using it when
504 * the function returns -1.
505 */
508 /**
509 * Finds and returns the value list, sorted in order of increasing priority
510 * for the configuration variable `key` and config set `cs`. When the
511 * configuration variable `key` is not found, returns 1 without touching
512 * `value`.
513 *
514 * The key will be parsed for validity with git_config_parse_key(), on
515 * error a negative value will be returned.
516 *
517 * The caller should not free or modify the returned pointer, as it is
518 * owned by the cache.
519 */
520 RESULT_MUST_BE_USED
524 /**
525 * A validation wrapper for git_configset_get_value_multi() which does
526 * for it what git_configset_get_string() does for
527 * git_configset_get_value().
528 *
529 * The configuration syntax allows for "[section] key", which will
530 * give us a NULL entry in the "struct string_list", as opposed to
531 * "[section] key =" which is the empty string. Most users of the API
532 * are not prepared to handle NULL in a "struct string_list".
533 */
537 /**
538 * Clears `config_set` structure, removes all saved variable-value pairs.
539 */
542 /*
543 * These functions return 1 if not found, and 0 if found, leaving the found
544 * value in the 'dest' pointer.
545 */
547 /**
548 * git_configset_get() returns negative values on error, see
549 * repo_config_get() below.
550 */
551 RESULT_MUST_BE_USED
554 /*
555 * Finds the highest-priority value for the configuration variable `key`
556 * and config set `cs`, stores the pointer to it in `value` and returns 0.
557 * When the configuration variable `key` is not found, returns 1 without
558 * touching `value`. The caller should not free or modify `value`, as it
559 * is owned by the cache.
560 */
568 int git_configset_get_bool_or_int(struct config_set *cs, const char *key, int *is_bool, int *dest);
572 /**
573 * Run only the discover part of the repo_config_get_*() functions
574 * below, in addition to 1 if not found, returns negative values on
575 * error (e.g. if the key itself is invalid).
576 */
580 /*
581 * Functions for reading protected config. By definition, protected
582 * config ignores repository config, so these do not take a `struct
583 * repository` parameter.
584 */
587 /**
588 * Querying For Specific Variables
589 * -------------------------------
590 *
591 * For programs wanting to query for specific variables in a non-callback
592 * manner, the config API provides two functions `repo_config_get_value`
593 * and `repo_config_get_value_multi`. They both read values from an internal
594 * cache generated previously from reading the config files.
595 *
596 * For those repo_config_get*() functions that aren't documented,
597 * consult the corresponding repo_config_get*() function's
598 * documentation.
599 */
601 RESULT_MUST_BE_USED
604 /**
605 * Finds the highest-priority value for the configuration variable `key`,
606 * stores the pointer to it in `value` and returns 0. When the
607 * configuration variable `key` is not found, returns 1 without touching
608 * `value`. The caller should not free or modify `value`, as it is owned
609 * by the cache.
610 */
613 /**
614 * Finds and returns the value list, sorted in order of increasing priority
615 * for the configuration variable `key`. When the configuration variable
616 * `key` is not found, returns 1 without touching `value`.
617 *
618 * The caller should not free or modify the returned pointer, as it is
619 * owned by the cache.
620 */
621 RESULT_MUST_BE_USED
624 RESULT_MUST_BE_USED
628 /**
629 * Resets and invalidates the config cache.
630 */
633 /**
634 * Allocates and copies the retrieved string into the `dest` parameter for
635 * the configuration variable `key`; if NULL string is given, prints an
636 * error message and returns -1. When the configuration variable `key` is
637 * not found, returns 1 without touching `dest`.
638 */
641 /**
642 * Similar to `repo_config_get_string`, but does not allocate any new
643 * memory; on success `dest` will point to memory owned by the config
644 * machinery, which could be invalidated if it is discarded and reloaded.
645 */
649 /**
650 * Finds and parses the value to an integer for the configuration variable
651 * `key`. Dies on error; otherwise, stores the value of the parsed integer in
652 * `dest` and returns 0. When the configuration variable `key` is not found,
653 * returns 1 without touching `dest`.
654 */
657 /**
658 * Similar to `repo_config_get_int` but for unsigned longs.
659 */
663 /**
664 * Finds and parses the value into a boolean value, for the configuration
665 * variable `key` respecting keywords like "true" and "false". Integer
666 * values are converted into true/false values (when they are non-zero or
667 * zero, respectively). Other values cause a die(). If parsing is successful,
668 * stores the value of the parsed result in `dest` and returns 0. When the
669 * configuration variable `key` is not found, returns 1 without touching
670 * `dest`.
671 */
674 /**
675 * Similar to `repo_config_get_bool`, except that integers are copied as-is,
676 * and `is_bool` flag is unset.
677 */
681 /**
682 * Similar to `repo_config_get_bool`, except that it returns -1 on error
683 * rather than dying.
684 */
692 /* This dies if the configured or default date is in the future */
695 /* parse either "this many days" integer, or "5.days.ago" approxidate */
699 /**
700 * First prints the error message specified by the caller in `err` and then
701 * dies printing the line number and the file name of the highest priority
702 * value for the configuration variable `key`.
703 */
707 /**
708 * Helper function which formats the die error message according to the
709 * parameters entered. Used by `git_die_config()`. It can be used by callers
710 * handling `repo_config_get_value_multi()` to print the correct error message
711 * for the desired value.
712 */
715 #define LOOKUP_CONFIG(mapping, var) \
716 lookup_config(mapping, ARRAY_SIZE(mapping), var)
719 # ifdef USE_THE_REPOSITORY_VARIABLE
721 {
723 }
726 {
728 }
731 {
733 }
736 {
738 }
741 {
743 }
747 {
749 }
752 {
754 }
757 {
759 }
762 {
764 }
767 {
769 }
772 {
774 }
777 {
779 }
782 {
784 }
787 {
789 }
793 {
795 }
798 {
800 }
803 {
805 }
812 {
815 }
823 {
827 }
835 {
838 }
842 {
845 }
849 {
852 }