1 #ifndef CONFIG_H 2 #define CONFIG_H 3 4 #include "hashmap.h" 5 #include "string-list.h" 6 7 8 /** 9 * The config API gives callers a way to access Git configuration files 10 * (and files which have the same syntax). 11 * 12 * General Usage 13 * ------------- 14 * 15 * Config files are parsed linearly, and each variable found is passed to a 16 * caller-provided callback function. The callback function is responsible 17 * for any actions to be taken on the config option, and is free to ignore 18 * some options. It is not uncommon for the configuration to be parsed 19 * several times during the run of a Git program, with different callbacks 20 * picking out different variables useful to themselves. 21 */ 22 23 struct object_id; 24 25 /* git_config_parse_key() returns these negated: */ 26 #define CONFIG_INVALID_KEY 1 27 #define CONFIG_NO_SECTION_OR_NAME 2 28 /* git_config_set_gently(), git_config_set_multivar_gently() return the above or these: */ 29 #define CONFIG_NO_LOCK -1 30 #define CONFIG_INVALID_FILE 3 31 #define CONFIG_NO_WRITE 4 32 #define CONFIG_NOTHING_SET 5 33 #define CONFIG_INVALID_PATTERN 6 34 #define CONFIG_GENERIC_ERROR 7 35 36 #define CONFIG_REGEX_NONE ((void *)1) 37 38 enum config_scope { 39 CONFIG_SCOPE_UNKNOWN = 0, 40 CONFIG_SCOPE_SYSTEM, 41 CONFIG_SCOPE_GLOBAL, 42 CONFIG_SCOPE_LOCAL, 43 CONFIG_SCOPE_WORKTREE, 44 CONFIG_SCOPE_COMMAND, 45 CONFIG_SCOPE_SUBMODULE, 46 }; 47 const char *config_scope_name(enum config_scope scope); 48 49 struct git_config_source { 50 unsigned int use_stdin:1; 51 const char *file; 52 /* The repository if blob is not NULL; leave blank for the_repository */ 53 struct repository *repo; 54 const char *blob; 55 enum config_scope scope; 56 }; 57 58 enum config_origin_type { 59 CONFIG_ORIGIN_BLOB, 60 CONFIG_ORIGIN_FILE, 61 CONFIG_ORIGIN_STDIN, 62 CONFIG_ORIGIN_SUBMODULE_BLOB, 63 CONFIG_ORIGIN_CMDLINE 64 }; 65 66 enum config_event_t { 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 }; 74 75 /* 76 * The parser event function (if not NULL) is called with the event type and 77 * the begin/end offsets of the parsed elements. 78 * 79 * Note: for CONFIG_EVENT_ENTRY (i.e. config variables), the trailing newline 80 * character is considered part of the element. 81 */ 82 typedef int (*config_parser_event_fn_t)(enum config_event_t type, 83 size_t begin_offset, size_t end_offset, 84 void *event_fn_data); 85 86 struct config_options { 87 unsigned int respect_includes : 1; 88 unsigned int ignore_repo : 1; 89 unsigned int ignore_worktree : 1; 90 unsigned int ignore_cmdline : 1; 91 unsigned int system_gently : 1; 92 const char *commondir; 93 const char *git_dir; 94 config_parser_event_fn_t event_fn; 95 void *event_fn_data; 96 enum config_error_action { 97 CONFIG_ERROR_UNSET = 0, /* use source-specific default */ 98 CONFIG_ERROR_DIE, /* die() on error */ 99 CONFIG_ERROR_ERROR, /* error() on error, return -1 */ 100 CONFIG_ERROR_SILENT, /* return -1 */ 101 } error_action; 102 }; 103 104 /** 105 * A config callback function takes three parameters: 106 * 107 * - the name of the parsed variable. This is in canonical "flat" form: the 108 * section, subsection, and variable segments will be separated by dots, 109 * and the section and variable segments will be all lowercase. E.g., 110 * `core.ignorecase`, `diff.SomeType.textconv`. 111 * 112 * - the value of the found variable, as a string. If the variable had no 113 * value specified, the value will be NULL (typically this means it 114 * should be interpreted as boolean true). 115 * 116 * - a void pointer passed in by the caller of the config API; this can 117 * contain callback-specific data 118 * 119 * A config callback should return 0 for success, or -1 if the variable 120 * could not be parsed properly. 121 */ 122 typedef int (*config_fn_t)(const char *, const char *, void *); 123 124 int git_default_config(const char *, const char *, void *); 125 126 /** 127 * Read a specific file in git-config format. 128 * This function takes the same callback and data parameters as `git_config`. 129 */ 130 int git_config_from_file(config_fn_t fn, const char *, void *); 131 132 int git_config_from_file_with_options(config_fn_t fn, const char *, 133 void *, 134 const struct config_options *); 135 int git_config_from_mem(config_fn_t fn, 136 const enum config_origin_type, 137 const char *name, 138 const char *buf, size_t len, 139 void *data, const struct config_options *opts); 140 int git_config_from_blob_oid(config_fn_t fn, const char *name, 141 struct repository *repo, 142 const struct object_id *oid, void *data); 143 void git_config_push_parameter(const char *text); 144 void git_config_push_env(const char *spec); 145 int git_config_from_parameters(config_fn_t fn, void *data); 146 void read_early_config(config_fn_t cb, void *data); 147 void read_very_early_config(config_fn_t cb, void *data); 148 149 /** 150 * Most programs will simply want to look up variables in all config files 151 * that Git knows about, using the normal precedence rules. To do this, 152 * call `git_config` with a callback function and void data pointer. 153 * 154 * `git_config` will read all config sources in order of increasing 155 * priority. Thus a callback should typically overwrite previously-seen 156 * entries with new ones (e.g., if both the user-wide `~/.gitconfig` and 157 * repo-specific `.git/config` contain `color.ui`, the config machinery 158 * will first feed the user-wide one to the callback, and then the 159 * repo-specific one; by overwriting, the higher-priority repo-specific 160 * value is left at the end). 161 */ 162 void git_config(config_fn_t fn, void *); 163 164 /** 165 * Lets the caller examine config while adjusting some of the default 166 * behavior of `git_config`. It should almost never be used by "regular" 167 * Git code that is looking up configuration variables. 168 * It is intended for advanced callers like `git-config`, which are 169 * intentionally tweaking the normal config-lookup process. 170 * It takes two extra parameters: 171 * 172 * - `config_source` 173 * If this parameter is non-NULL, it specifies the source to parse for 174 * configuration, rather than looking in the usual files. See `struct 175 * git_config_source` in `config.h` for details. Regular `git_config` defaults 176 * to `NULL`. 177 * 178 * - `opts` 179 * Specify options to adjust the behavior of parsing config files. See `struct 180 * config_options` in `config.h` for details. As an example: regular `git_config` 181 * sets `opts.respect_includes` to `1` by default. 182 */ 183 int config_with_options(config_fn_t fn, void *, 184 struct git_config_source *config_source, 185 const struct config_options *opts); 186 187 /** 188 * Value Parsing Helpers 189 * --------------------- 190 * 191 * The following helper functions aid in parsing string values 192 */ 193 194 int git_parse_ssize_t(const char *, ssize_t *); 195 int git_parse_ulong(const char *, unsigned long *); 196 197 /** 198 * Same as `git_config_bool`, except that it returns -1 on error rather 199 * than dying. 200 */ 201 int git_parse_maybe_bool(const char *); 202 203 /** 204 * Parse the string to an integer, including unit factors. Dies on error; 205 * otherwise, returns the parsed result. 206 */ 207 int git_config_int(const char *, const char *); 208 209 int64_t git_config_int64(const char *, const char *); 210 211 /** 212 * Identical to `git_config_int`, but for unsigned longs. 213 */ 214 unsigned long git_config_ulong(const char *, const char *); 215 216 ssize_t git_config_ssize_t(const char *, const char *); 217 218 /** 219 * Same as `git_config_bool`, except that integers are returned as-is, and 220 * an `is_bool` flag is unset. 221 */ 222 int git_config_bool_or_int(const char *, const char *, int *); 223 224 /** 225 * Parse a string into a boolean value, respecting keywords like "true" and 226 * "false". Integer values are converted into true/false values (when they 227 * are non-zero or zero, respectively). Other values cause a die(). If 228 * parsing is successful, the return value is the result. 229 */ 230 int git_config_bool(const char *, const char *); 231 232 /** 233 * Allocates and copies the value string into the `dest` parameter; if no 234 * string is given, prints an error message and returns -1. 235 */ 236 int git_config_string(const char **, const char *, const char *); 237 238 /** 239 * Similar to `git_config_string`, but expands `~` or `~user` into the 240 * user's home directory when found at the beginning of the path. 241 */ 242 int git_config_pathname(const char **, const char *, const char *); 243 244 int git_config_expiry_date(timestamp_t *, const char *, const char *); 245 int git_config_color(char *, const char *, const char *); 246 int git_config_set_in_file_gently(const char *, const char *, const char *); 247 248 /** 249 * write config values to a specific config file, takes a key/value pair as 250 * parameter. 251 */ 252 void git_config_set_in_file(const char *, const char *, const char *); 253 254 int git_config_set_gently(const char *, const char *); 255 256 /** 257 * write config values to `.git/config`, takes a key/value pair as parameter. 258 */ 259 void git_config_set(const char *, const char *); 260 261 int git_config_parse_key(const char *, char **, size_t *); 262 263 /* 264 * The following macros specify flag bits that alter the behavior 265 * of the git_config_set_multivar*() methods. 266 */ 267 268 /* 269 * When CONFIG_FLAGS_MULTI_REPLACE is specified, all matching key/values 270 * are removed before a single new pair is written. If the flag is not 271 * present, then set operations replace only the first match. 272 */ 273 #define CONFIG_FLAGS_MULTI_REPLACE (1 << 0) 274 275 /* 276 * When CONFIG_FLAGS_FIXED_VALUE is specified, match key/value pairs 277 * by string comparison (not regex match) to the provided value_pattern 278 * parameter. 279 */ 280 #define CONFIG_FLAGS_FIXED_VALUE (1 << 1) 281 282 int git_config_set_multivar_gently(const char *, const char *, const char *, unsigned); 283 void git_config_set_multivar(const char *, const char *, const char *, unsigned); 284 int git_config_set_multivar_in_file_gently(const char *, const char *, const char *, const char *, unsigned); 285 286 /** 287 * takes four parameters: 288 * 289 * - the name of the file, as a string, to which key/value pairs will be written. 290 * 291 * - the name of key, as a string. This is in canonical "flat" form: the section, 292 * subsection, and variable segments will be separated by dots, and the section 293 * and variable segments will be all lowercase. 294 * E.g., `core.ignorecase`, `diff.SomeType.textconv`. 295 * 296 * - the value of the variable, as a string. If value is equal to NULL, it will 297 * remove the matching key from the config file. 298 * 299 * - the value regex, as a string. It will disregard key/value pairs where value 300 * does not match. 301 * 302 * - a flags value with bits corresponding to the CONFIG_FLAG_* macros. 303 * 304 * It returns 0 on success. 305 */ 306 void git_config_set_multivar_in_file(const char *config_filename, 307 const char *key, 308 const char *value, 309 const char *value_pattern, 310 unsigned flags); 311 312 /** 313 * rename or remove sections in the config file 314 * parameters `old_name` and `new_name` 315 * If NULL is passed through `new_name` parameter, 316 * the section will be removed from the config file. 317 */ 318 int git_config_rename_section(const char *, const char *); 319 320 int git_config_rename_section_in_file(const char *, const char *, const char *); 321 int git_config_copy_section(const char *, const char *); 322 int git_config_copy_section_in_file(const char *, const char *, const char *); 323 int git_env_bool(const char *, int); 324 unsigned long git_env_ulong(const char *, unsigned long); 325 int git_config_system(void); 326 int config_error_nonbool(const char *); 327 #if defined(__GNUC__) 328 #define config_error_nonbool(s) (config_error_nonbool(s), const_error()) 329 #endif 330 331 char *git_system_config(void); 332 void git_global_config(char **user, char **xdg); 333 334 int git_config_parse_parameter(const char *, config_fn_t fn, void *data); 335 336 enum config_scope current_config_scope(void); 337 const char *current_config_origin_type(void); 338 const char *current_config_name(void); 339 int current_config_line(void); 340 341 /** 342 * Include Directives 343 * ------------------ 344 * 345 * By default, the config parser does not respect include directives. 346 * However, a caller can use the special `git_config_include` wrapper 347 * callback to support them. To do so, you simply wrap your "real" callback 348 * function and data pointer in a `struct config_include_data`, and pass 349 * the wrapper to the regular config-reading functions. For example: 350 * 351 * ------------------------------------------- 352 * int read_file_with_include(const char *file, config_fn_t fn, void *data) 353 * { 354 * struct config_include_data inc = CONFIG_INCLUDE_INIT; 355 * inc.fn = fn; 356 * inc.data = data; 357 * return git_config_from_file(git_config_include, file, &inc); 358 * } 359 * ------------------------------------------- 360 * 361 * `git_config` respects includes automatically. The lower-level 362 * `git_config_from_file` does not. 363 * 364 */ 365 struct config_include_data { 366 int depth; 367 config_fn_t fn; 368 void *data; 369 const struct config_options *opts; 370 }; 371 #define CONFIG_INCLUDE_INIT { 0 } 372 int git_config_include(const char *name, const char *value, void *data); 373 374 /* 375 * Match and parse a config key of the form: 376 * 377 * section.(subsection.)?key 378 * 379 * (i.e., what gets handed to a config_fn_t). The caller provides the section; 380 * we return -1 if it does not match, 0 otherwise. The subsection and key 381 * out-parameters are filled by the function (and *subsection is NULL if it is 382 * missing). 383 * 384 * If the subsection pointer-to-pointer passed in is NULL, returns 0 only if 385 * there is no subsection at all. 386 */ 387 int parse_config_key(const char *var, 388 const char *section, 389 const char **subsection, size_t *subsection_len, 390 const char **key); 391 392 /** 393 * Custom Configsets 394 * ----------------- 395 * 396 * A `config_set` can be used to construct an in-memory cache for 397 * config-like files that the caller specifies (i.e., files like `.gitmodules`, 398 * `~/.gitconfig` etc.). For example, 399 * 400 * ---------------------------------------- 401 * struct config_set gm_config; 402 * git_configset_init(&gm_config); 403 * int b; 404 * //we add config files to the config_set 405 * git_configset_add_file(&gm_config, ".gitmodules"); 406 * git_configset_add_file(&gm_config, ".gitmodules_alt"); 407 * 408 * if (!git_configset_get_bool(gm_config, "submodule.frotz.ignore", &b)) { 409 * //hack hack hack 410 * } 411 * 412 * when we are done with the configset: 413 * git_configset_clear(&gm_config); 414 * ---------------------------------------- 415 * 416 * Configset API provides functions for the above mentioned work flow 417 */ 418 419 struct config_set_element { 420 struct hashmap_entry ent; 421 char *key; 422 struct string_list value_list; 423 }; 424 425 struct configset_list_item { 426 struct config_set_element *e; 427 int value_index; 428 }; 429 430 /* 431 * the contents of the list are ordered according to their 432 * position in the config files and order of parsing the files. 433 * (i.e. key-value pair at the last position of .git/config will 434 * be at the last item of the list) 435 */ 436 struct configset_list { 437 struct configset_list_item *items; 438 unsigned int nr, alloc; 439 }; 440 441 struct config_set { 442 struct hashmap config_hash; 443 int hash_initialized; 444 struct configset_list list; 445 }; 446 447 /** 448 * Initializes the config_set `cs`. 449 */ 450 void git_configset_init(struct config_set *cs); 451 452 /** 453 * Parses the file and adds the variable-value pairs to the `config_set`, 454 * dies if there is an error in parsing the file. Returns 0 on success, or 455 * -1 if the file does not exist or is inaccessible. The caller decides 456 * whether to free the incomplete configset or continue using it when 457 * the function returns -1. 458 */ 459 int git_configset_add_file(struct config_set *cs, const char *filename); 460 461 /** 462 * Finds and returns the value list, sorted in order of increasing priority 463 * for the configuration variable `key` and config set `cs`. When the 464 * configuration variable `key` is not found, returns NULL. The caller 465 * should not free or modify the returned pointer, as it is owned by the cache. 466 */ 467 const struct string_list *git_configset_get_value_multi(struct config_set *cs, const char *key); 468 469 /** 470 * Clears `config_set` structure, removes all saved variable-value pairs. 471 */ 472 void git_configset_clear(struct config_set *cs); 473 474 /* 475 * These functions return 1 if not found, and 0 if found, leaving the found 476 * value in the 'dest' pointer. 477 */ 478 479 /* 480 * Finds the highest-priority value for the configuration variable `key` 481 * and config set `cs`, stores the pointer to it in `value` and returns 0. 482 * When the configuration variable `key` is not found, returns 1 without 483 * touching `value`. The caller should not free or modify `value`, as it 484 * is owned by the cache. 485 */ 486 int git_configset_get_value(struct config_set *cs, const char *key, const char **dest); 487 488 int git_configset_get_string(struct config_set *cs, const char *key, char **dest); 489 int git_configset_get_string_tmp(struct config_set *cs, const char *key, const char **dest); 490 int git_configset_get_int(struct config_set *cs, const char *key, int *dest); 491 int git_configset_get_ulong(struct config_set *cs, const char *key, unsigned long *dest); 492 int git_configset_get_bool(struct config_set *cs, const char *key, int *dest); 493 int git_configset_get_bool_or_int(struct config_set *cs, const char *key, int *is_bool, int *dest); 494 int git_configset_get_maybe_bool(struct config_set *cs, const char *key, int *dest); 495 int git_configset_get_pathname(struct config_set *cs, const char *key, const char **dest); 496 497 /* Functions for reading a repository's config */ 498 struct repository; 499 void repo_config(struct repository *repo, config_fn_t fn, void *data); 500 int repo_config_get_value(struct repository *repo, 501 const char *key, const char **value); 502 const struct string_list *repo_config_get_value_multi(struct repository *repo, 503 const char *key); 504 int repo_config_get_string(struct repository *repo, 505 const char *key, char **dest); 506 int repo_config_get_string_tmp(struct repository *repo, 507 const char *key, const char **dest); 508 int repo_config_get_int(struct repository *repo, 509 const char *key, int *dest); 510 int repo_config_get_ulong(struct repository *repo, 511 const char *key, unsigned long *dest); 512 int repo_config_get_bool(struct repository *repo, 513 const char *key, int *dest); 514 int repo_config_get_bool_or_int(struct repository *repo, 515 const char *key, int *is_bool, int *dest); 516 int repo_config_get_maybe_bool(struct repository *repo, 517 const char *key, int *dest); 518 int repo_config_get_pathname(struct repository *repo, 519 const char *key, const char **dest); 520 521 /** 522 * Querying For Specific Variables 523 * ------------------------------- 524 * 525 * For programs wanting to query for specific variables in a non-callback 526 * manner, the config API provides two functions `git_config_get_value` 527 * and `git_config_get_value_multi`. They both read values from an internal 528 * cache generated previously from reading the config files. 529 */ 530 531 /** 532 * Finds the highest-priority value for the configuration variable `key`, 533 * stores the pointer to it in `value` and returns 0. When the 534 * configuration variable `key` is not found, returns 1 without touching 535 * `value`. The caller should not free or modify `value`, as it is owned 536 * by the cache. 537 */ 538 int git_config_get_value(const char *key, const char **value); 539 540 /** 541 * Finds and returns the value list, sorted in order of increasing priority 542 * for the configuration variable `key`. When the configuration variable 543 * `key` is not found, returns NULL. The caller should not free or modify 544 * the returned pointer, as it is owned by the cache. 545 */ 546 const struct string_list *git_config_get_value_multi(const char *key); 547 548 /** 549 * Resets and invalidates the config cache. 550 */ 551 void git_config_clear(void); 552 553 /** 554 * Allocates and copies the retrieved string into the `dest` parameter for 555 * the configuration variable `key`; if NULL string is given, prints an 556 * error message and returns -1. When the configuration variable `key` is 557 * not found, returns 1 without touching `dest`. 558 */ 559 int git_config_get_string(const char *key, char **dest); 560 561 /** 562 * Similar to `git_config_get_string`, but does not allocate any new 563 * memory; on success `dest` will point to memory owned by the config 564 * machinery, which could be invalidated if it is discarded and reloaded. 565 */ 566 int git_config_get_string_tmp(const char *key, const char **dest); 567 568 /** 569 * Finds and parses the value to an integer for the configuration variable 570 * `key`. Dies on error; otherwise, stores the value of the parsed integer in 571 * `dest` and returns 0. When the configuration variable `key` is not found, 572 * returns 1 without touching `dest`. 573 */ 574 int git_config_get_int(const char *key, int *dest); 575 576 /** 577 * Similar to `git_config_get_int` but for unsigned longs. 578 */ 579 int git_config_get_ulong(const char *key, unsigned long *dest); 580 581 /** 582 * Finds and parses the value into a boolean value, for the configuration 583 * variable `key` respecting keywords like "true" and "false". Integer 584 * values are converted into true/false values (when they are non-zero or 585 * zero, respectively). Other values cause a die(). If parsing is successful, 586 * stores the value of the parsed result in `dest` and returns 0. When the 587 * configuration variable `key` is not found, returns 1 without touching 588 * `dest`. 589 */ 590 int git_config_get_bool(const char *key, int *dest); 591 592 /** 593 * Similar to `git_config_get_bool`, except that integers are copied as-is, 594 * and `is_bool` flag is unset. 595 */ 596 int git_config_get_bool_or_int(const char *key, int *is_bool, int *dest); 597 598 /** 599 * Similar to `git_config_get_bool`, except that it returns -1 on error 600 * rather than dying. 601 */ 602 int git_config_get_maybe_bool(const char *key, int *dest); 603 604 /** 605 * Similar to `git_config_get_string`, but expands `~` or `~user` into 606 * the user's home directory when found at the beginning of the path. 607 */ 608 int git_config_get_pathname(const char *key, const char **dest); 609 610 int git_config_get_index_threads(int *dest); 611 int git_config_get_split_index(void); 612 int git_config_get_max_percent_split_change(void); 613 int git_config_get_fsmonitor(void); 614 615 /* This dies if the configured or default date is in the future */ 616 int git_config_get_expiry(const char *key, const char **output); 617 618 /* parse either "this many days" integer, or "5.days.ago" approxidate */ 619 int git_config_get_expiry_in_days(const char *key, timestamp_t *, timestamp_t now); 620 621 struct key_value_info { 622 const char *filename; 623 int linenr; 624 enum config_origin_type origin_type; 625 enum config_scope scope; 626 }; 627 628 /** 629 * First prints the error message specified by the caller in `err` and then 630 * dies printing the line number and the file name of the highest priority 631 * value for the configuration variable `key`. 632 */ 633 NORETURN void git_die_config(const char *key, const char *err, ...) __attribute__((format(printf, 2, 3))); 634 635 /** 636 * Helper function which formats the die error message according to the 637 * parameters entered. Used by `git_die_config()`. It can be used by callers 638 * handling `git_config_get_value_multi()` to print the correct error message 639 * for the desired value. 640 */ 641 NORETURN void git_die_config_linenr(const char *key, const char *filename, int linenr); 642 643 #define LOOKUP_CONFIG(mapping, var) \ 644 lookup_config(mapping, ARRAY_SIZE(mapping), var) 645 int lookup_config(const char **mapping, int nr_mapping, const char *var); 646 647 #endif /* CONFIG_H */ 648