| 1 | #ifndef CONFIG_H |
| 2 | #define CONFIG_H |
| 3 | |
| 4 | #include "hashmap.h" |
| 5 | #include "string-list.h" |
| 6 | #include "repository.h" |
| 7 | #include "parse.h" |
| 8 | |
| 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 | */ |
| 23 | |
| 24 | struct object_id; |
| 25 | |
| 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 |
| 36 | |
| 37 | #define CONFIG_REGEX_NONE ((void *)1) |
| 38 | |
| 39 | enum config_scope { |
| 40 | CONFIG_SCOPE_UNKNOWN = 0, |
| 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 | }; |
| 48 | const char *config_scope_name(enum config_scope scope); |
| 49 | |
| 50 | struct git_config_source { |
| 51 | unsigned int use_stdin:1; |
| 52 | const char *file; |
| 53 | const char *blob; |
| 54 | enum config_scope scope; |
| 55 | }; |
| 56 | |
| 57 | enum config_origin_type { |
| 58 | CONFIG_ORIGIN_UNKNOWN = 0, |
| 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 | struct config_source; |
| 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 | */ |
| 83 | typedef int (*config_parser_event_fn_t)(enum config_event_t type, |
| 84 | size_t begin_offset, size_t end_offset, |
| 85 | struct config_source *cs, |
| 86 | void *event_fn_data); |
| 87 | |
| 88 | struct config_options { |
| 89 | unsigned int respect_includes : 1; |
| 90 | unsigned int ignore_repo : 1; |
| 91 | unsigned int ignore_worktree : 1; |
| 92 | unsigned int ignore_cmdline : 1; |
| 93 | unsigned int system_gently : 1; |
| 94 | |
| 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 | */ |
| 101 | unsigned int unconditional_remote_url : 1; |
| 102 | |
| 103 | const char *commondir; |
| 104 | const char *git_dir; |
| 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; |
| 110 | void *event_fn_data; |
| 111 | enum config_error_action { |
| 112 | CONFIG_ERROR_UNSET = 0, /* use source-specific default */ |
| 113 | CONFIG_ERROR_DIE, /* die() on error */ |
| 114 | CONFIG_ERROR_ERROR, /* error() on error, return -1 */ |
| 115 | CONFIG_ERROR_SILENT, /* return -1 */ |
| 116 | } error_action; |
| 117 | }; |
| 118 | |
| 119 | /* Config source metadata for a given config key-value pair */ |
| 120 | struct key_value_info { |
| 121 | const char *filename; |
| 122 | int linenr; |
| 123 | enum config_origin_type origin_type; |
| 124 | enum config_scope scope; |
| 125 | }; |
| 126 | #define KVI_INIT { \ |
| 127 | .filename = NULL, \ |
| 128 | .linenr = -1, \ |
| 129 | .origin_type = CONFIG_ORIGIN_UNKNOWN, \ |
| 130 | .scope = CONFIG_SCOPE_UNKNOWN, \ |
| 131 | } |
| 132 | |
| 133 | /* Captures additional information that a config callback can use. */ |
| 134 | struct config_context { |
| 135 | /* Config source metadata for key and value. */ |
| 136 | const struct key_value_info *kvi; |
| 137 | }; |
| 138 | #define CONFIG_CONTEXT_INIT { 0 } |
| 139 | |
| 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 | */ |
| 163 | typedef int (*config_fn_t)(const char *, const char *, |
| 164 | const struct config_context *, void *); |
| 165 | |
| 166 | /** |
| 167 | * Read a specific file in git-config format. |
| 168 | * This function takes the same callback and data parameters as `repo_config`. |
| 169 | * |
| 170 | * Unlike repo_config(), this function does not respect includes. |
| 171 | */ |
| 172 | int git_config_from_file(config_fn_t fn, const char *, void *); |
| 173 | |
| 174 | int git_config_from_file_with_options(config_fn_t fn, const char *, |
| 175 | void *, enum config_scope, |
| 176 | const struct config_options *); |
| 177 | int git_config_from_mem(config_fn_t fn, |
| 178 | const enum config_origin_type, |
| 179 | const char *name, |
| 180 | const char *buf, size_t len, |
| 181 | void *data, enum config_scope scope, |
| 182 | const struct config_options *opts); |
| 183 | int git_config_from_blob_oid(config_fn_t fn, const char *name, |
| 184 | struct repository *repo, |
| 185 | const struct object_id *oid, void *data, |
| 186 | enum config_scope scope); |
| 187 | void git_config_push_parameter(const char *text); |
| 188 | void git_config_push_env(const char *spec); |
| 189 | int git_config_from_parameters(config_fn_t fn, void *data); |
| 190 | |
| 191 | /* |
| 192 | * Read config when the Git directory has not yet been set up. In case |
| 193 | * `the_repository` has not yet been set up, try to discover the Git |
| 194 | * directory to read the configuration from. |
| 195 | */ |
| 196 | void read_early_config(struct repository *repo, config_fn_t cb, void *data); |
| 197 | |
| 198 | /* |
| 199 | * Read config but only enumerate system and global settings. |
| 200 | * Omit any repo-local, worktree-local, or command-line settings. |
| 201 | */ |
| 202 | void read_very_early_config(config_fn_t cb, void *data); |
| 203 | |
| 204 | /** |
| 205 | * Most programs will simply want to look up variables in all config files |
| 206 | * that Git knows about, using the normal precedence rules. To do this, |
| 207 | * call `repo_config` with a callback function and void data pointer. |
| 208 | * |
| 209 | * `repo_config` will read all config sources in order of increasing |
| 210 | * priority. Thus a callback should typically overwrite previously-seen |
| 211 | * entries with new ones (e.g., if both the user-wide `~/.gitconfig` and |
| 212 | * repo-specific `.git/config` contain `color.ui`, the config machinery |
| 213 | * will first feed the user-wide one to the callback, and then the |
| 214 | * repo-specific one; by overwriting, the higher-priority repo-specific |
| 215 | * value is left at the end). |
| 216 | * |
| 217 | * In cases where the repository variable is NULL, repo_config() will |
| 218 | * skip the per-repository config but retain system and global configs |
| 219 | * by calling read_very_early_config() which also ignores one-time |
| 220 | * overrides like "git -c var=val". This is to support handling "git foo -h" |
| 221 | * (which lets git.c:run_builtin() to pass NULL and have the cmd_foo() |
| 222 | * call repo_config() before calling parse_options() to notice "-h", give |
| 223 | * help and exit) for a command that ordinarily require a repository |
| 224 | * so this limitation may be OK (but if needed you are welcome to fix it). |
| 225 | * |
| 226 | * Unlike git_config_from_file(), this function respects includes. |
| 227 | */ |
| 228 | void repo_config(struct repository *r, config_fn_t fn, void *); |
| 229 | |
| 230 | /** |
| 231 | * Lets the caller examine config while adjusting some of the default |
| 232 | * behavior of `repo_config`. It should almost never be used by "regular" |
| 233 | * Git code that is looking up configuration variables. |
| 234 | * It is intended for advanced callers like `git-config`, which are |
| 235 | * intentionally tweaking the normal config-lookup process. |
| 236 | * It takes two extra parameters: |
| 237 | * |
| 238 | * - `config_source` |
| 239 | * If this parameter is non-NULL, it specifies the source to parse for |
| 240 | * configuration, rather than looking in the usual files. See `struct |
| 241 | * git_config_source` in `config.h` for details. Regular `repo_config` defaults |
| 242 | * to `NULL`. |
| 243 | * |
| 244 | * - `opts` |
| 245 | * Specify options to adjust the behavior of parsing config files. See `struct |
| 246 | * config_options` in `config.h` for details. As an example: regular `repo_config` |
| 247 | * sets `opts.respect_includes` to `1` by default. |
| 248 | */ |
| 249 | int config_with_options(config_fn_t fn, void *, |
| 250 | const struct git_config_source *config_source, |
| 251 | struct repository *repo, |
| 252 | const struct config_options *opts); |
| 253 | |
| 254 | /** |
| 255 | * Value Parsing Helpers |
| 256 | * --------------------- |
| 257 | * |
| 258 | * The following helper functions aid in parsing string values |
| 259 | */ |
| 260 | |
| 261 | /** |
| 262 | * Parse the string to an integer, including unit factors. Dies on error; |
| 263 | * otherwise, returns the parsed result. |
| 264 | */ |
| 265 | int git_config_int(const char *, const char *, const struct key_value_info *); |
| 266 | |
| 267 | int64_t git_config_int64(const char *, const char *, |
| 268 | const struct key_value_info *); |
| 269 | |
| 270 | /** |
| 271 | * Identical to `git_config_int`, but for unsigned ints. |
| 272 | */ |
| 273 | unsigned int git_config_uint(const char *, const char *, |
| 274 | const struct key_value_info *); |
| 275 | |
| 276 | /** |
| 277 | * Identical to `git_config_int`, but for unsigned longs. |
| 278 | */ |
| 279 | unsigned long git_config_ulong(const char *, const char *, |
| 280 | const struct key_value_info *); |
| 281 | |
| 282 | ssize_t git_config_ssize_t(const char *, const char *, |
| 283 | const struct key_value_info *); |
| 284 | |
| 285 | /** |
| 286 | * Identically to `git_config_double`, but for double-precision floating point |
| 287 | * values. |
| 288 | */ |
| 289 | double git_config_double(const char *, const char *, |
| 290 | const struct key_value_info *); |
| 291 | |
| 292 | /** |
| 293 | * Same as `git_config_bool`, except that integers are returned as-is, and |
| 294 | * an `is_bool` flag is unset. |
| 295 | */ |
| 296 | int git_config_bool_or_int(const char *, const char *, |
| 297 | const struct key_value_info *, int *); |
| 298 | |
| 299 | /** |
| 300 | * Parse a string into a boolean value, respecting keywords like "true" and |
| 301 | * "false". Integer values are converted into true/false values (when they |
| 302 | * are non-zero or zero, respectively). Other values cause a die(). If |
| 303 | * parsing is successful, the return value is the result. |
| 304 | */ |
| 305 | int git_config_bool(const char *, const char *); |
| 306 | |
| 307 | /** |
| 308 | * Allocates and copies the value string into the `dest` parameter; if no |
| 309 | * string is given, prints an error message and returns -1. |
| 310 | */ |
| 311 | int git_config_string(char **, const char *, const char *); |
| 312 | |
| 313 | /** |
| 314 | * Similar to `git_config_string`, but expands `~` or `~user` into the |
| 315 | * user's home directory when found at the beginning of the path. |
| 316 | */ |
| 317 | int git_config_pathname(char **, const char *, const char *); |
| 318 | |
| 319 | int git_config_expiry_date(timestamp_t *, const char *, const char *); |
| 320 | int git_config_color(char *, const char *, const char *); |
| 321 | int repo_config_set_in_file_gently(struct repository *r, const char *config_filename, |
| 322 | const char *key, const char *comment, const char *value); |
| 323 | |
| 324 | /** |
| 325 | * write config values to a specific config file, takes a key/value pair as |
| 326 | * parameter. |
| 327 | */ |
| 328 | void repo_config_set_in_file(struct repository *, const char *, const char *, const char *); |
| 329 | |
| 330 | int repo_config_set_gently(struct repository *r, const char *, const char *); |
| 331 | |
| 332 | /** |
| 333 | * Write a config value that should apply to the current worktree. If |
| 334 | * extensions.worktreeConfig is enabled, then the write will happen in the |
| 335 | * current worktree's config. Otherwise, write to the common config file. |
| 336 | */ |
| 337 | int repo_config_set_worktree_gently(struct repository *, const char *, const char *); |
| 338 | |
| 339 | /** |
| 340 | * write config values to `.git/config`, takes a key/value pair as parameter. |
| 341 | */ |
| 342 | void repo_config_set(struct repository *, const char *, const char *); |
| 343 | |
| 344 | int git_config_parse_key(const char *, char **, size_t *); |
| 345 | |
| 346 | int git_config_key_is_valid(const char *); |
| 347 | |
| 348 | /* |
| 349 | * The following macros specify flag bits that alter the behavior |
| 350 | * of the repo_config_set_multivar*() methods. |
| 351 | */ |
| 352 | |
| 353 | /* |
| 354 | * When CONFIG_FLAGS_MULTI_REPLACE is specified, all matching key/values |
| 355 | * are removed before a single new pair is written. If the flag is not |
| 356 | * present, then set operations replace only the first match. |
| 357 | */ |
| 358 | #define CONFIG_FLAGS_MULTI_REPLACE (1 << 0) |
| 359 | |
| 360 | /* |
| 361 | * When CONFIG_FLAGS_FIXED_VALUE is specified, match key/value pairs |
| 362 | * by string comparison (not regex match) to the provided value_pattern |
| 363 | * parameter. |
| 364 | */ |
| 365 | #define CONFIG_FLAGS_FIXED_VALUE (1 << 1) |
| 366 | |
| 367 | int repo_config_set_multivar_gently(struct repository *, const char *, const char *, const char *, unsigned); |
| 368 | void repo_config_set_multivar(struct repository *r, const char *, const char *, const char *, unsigned); |
| 369 | int repo_config_set_multivar_in_file_gently(struct repository *, const char *, const char *, const char *, const char *, const char *, unsigned); |
| 370 | |
| 371 | char *git_config_prepare_comment_string(const char *); |
| 372 | |
| 373 | /** |
| 374 | * takes four parameters: |
| 375 | * |
| 376 | * - the name of the file, as a string, to which key/value pairs will be written. |
| 377 | * |
| 378 | * - the name of key, as a string. This is in canonical "flat" form: the section, |
| 379 | * subsection, and variable segments will be separated by dots, and the section |
| 380 | * and variable segments will be all lowercase. |
| 381 | * E.g., `core.ignorecase`, `diff.SomeType.textconv`. |
| 382 | * |
| 383 | * - the value of the variable, as a string. If value is equal to NULL, it will |
| 384 | * remove the matching key from the config file. |
| 385 | * |
| 386 | * - the value regex, as a string. It will disregard key/value pairs where value |
| 387 | * does not match. |
| 388 | * |
| 389 | * - a flags value with bits corresponding to the CONFIG_FLAG_* macros. |
| 390 | * |
| 391 | * It returns 0 on success. |
| 392 | */ |
| 393 | void repo_config_set_multivar_in_file(struct repository *r, |
| 394 | const char *config_filename, |
| 395 | const char *key, |
| 396 | const char *value, |
| 397 | const char *value_pattern, |
| 398 | unsigned flags); |
| 399 | |
| 400 | /** |
| 401 | * rename or remove sections in the config file |
| 402 | * parameters `old_name` and `new_name` |
| 403 | * If NULL is passed through `new_name` parameter, |
| 404 | * the section will be removed from the config file. |
| 405 | */ |
| 406 | int repo_config_rename_section(struct repository *, const char *, const char *); |
| 407 | |
| 408 | int repo_config_rename_section_in_file(struct repository *, const char *, const char *, const char *); |
| 409 | int repo_config_copy_section(struct repository *, const char *, const char *); |
| 410 | int repo_config_copy_section_in_file(struct repository *, const char *, const char *, const char *); |
| 411 | int git_config_system(void); |
| 412 | int config_error_nonbool(const char *); |
| 413 | #if defined(__GNUC__) |
| 414 | #define config_error_nonbool(s) (config_error_nonbool(s), const_error()) |
| 415 | #endif |
| 416 | |
| 417 | char *git_system_config(void); |
| 418 | char *git_global_config(void); |
| 419 | void git_global_config_paths(char **user, char **xdg); |
| 420 | |
| 421 | int git_config_parse_parameter(const char *, config_fn_t fn, void *data); |
| 422 | |
| 423 | const char *config_origin_type_name(enum config_origin_type type); |
| 424 | void kvi_from_param(struct key_value_info *out); |
| 425 | |
| 426 | /* |
| 427 | * Match and parse a config key of the form: |
| 428 | * |
| 429 | * section.(subsection.)?key |
| 430 | * |
| 431 | * (i.e., what gets handed to a config_fn_t). The caller provides the section; |
| 432 | * we return -1 if it does not match, 0 otherwise. The subsection and key |
| 433 | * out-parameters are filled by the function (and *subsection is NULL if it is |
| 434 | * missing). |
| 435 | * |
| 436 | * If the subsection pointer-to-pointer passed in is NULL, returns 0 only if |
| 437 | * there is no subsection at all. |
| 438 | */ |
| 439 | int parse_config_key(const char *var, |
| 440 | const char *section, |
| 441 | const char **subsection, size_t *subsection_len, |
| 442 | const char **key); |
| 443 | |
| 444 | /** |
| 445 | * Custom Configsets |
| 446 | * ----------------- |
| 447 | * |
| 448 | * A `config_set` can be used to construct an in-memory cache for |
| 449 | * config-like files that the caller specifies (i.e., files like `.gitmodules`, |
| 450 | * `~/.gitconfig` etc.). For example, |
| 451 | * |
| 452 | * ---------------------------------------- |
| 453 | * struct config_set gm_config; |
| 454 | * git_configset_init(&gm_config); |
| 455 | * int b; |
| 456 | * //we add config files to the config_set |
| 457 | * git_configset_add_file(&gm_config, ".gitmodules"); |
| 458 | * git_configset_add_file(&gm_config, ".gitmodules_alt"); |
| 459 | * |
| 460 | * if (!git_configset_get_bool(gm_config, "submodule.frotz.ignore", &b)) { |
| 461 | * //hack hack hack |
| 462 | * } |
| 463 | * |
| 464 | * when we are done with the configset: |
| 465 | * git_configset_clear(&gm_config); |
| 466 | * ---------------------------------------- |
| 467 | * |
| 468 | * Configset API provides functions for the above mentioned work flow |
| 469 | */ |
| 470 | |
| 471 | struct config_set_element { |
| 472 | struct hashmap_entry ent; |
| 473 | char *key; |
| 474 | struct string_list value_list; |
| 475 | }; |
| 476 | |
| 477 | struct configset_list_item { |
| 478 | struct config_set_element *e; |
| 479 | int value_index; |
| 480 | }; |
| 481 | |
| 482 | /* |
| 483 | * the contents of the list are ordered according to their |
| 484 | * position in the config files and order of parsing the files. |
| 485 | * (i.e. key-value pair at the last position of .git/config will |
| 486 | * be at the last item of the list) |
| 487 | */ |
| 488 | struct configset_list { |
| 489 | struct configset_list_item *items; |
| 490 | unsigned int nr, alloc; |
| 491 | }; |
| 492 | |
| 493 | struct config_set { |
| 494 | struct hashmap config_hash; |
| 495 | int hash_initialized; |
| 496 | struct configset_list list; |
| 497 | }; |
| 498 | |
| 499 | /** |
| 500 | * Initializes the config_set `cs`. |
| 501 | */ |
| 502 | void git_configset_init(struct config_set *cs); |
| 503 | |
| 504 | /** |
| 505 | * Parses the file and adds the variable-value pairs to the `config_set`, |
| 506 | * dies if there is an error in parsing the file. Returns 0 on success, or |
| 507 | * -1 if the file does not exist or is inaccessible. The caller decides |
| 508 | * whether to free the incomplete configset or continue using it when |
| 509 | * the function returns -1. |
| 510 | */ |
| 511 | int git_configset_add_file(struct config_set *cs, const char *filename); |
| 512 | |
| 513 | /** |
| 514 | * Finds and returns the value list, sorted in order of increasing priority |
| 515 | * for the configuration variable `key` and config set `cs`. When the |
| 516 | * configuration variable `key` is not found, returns 1 without touching |
| 517 | * `value`. |
| 518 | * |
| 519 | * The key will be parsed for validity with git_config_parse_key(), on |
| 520 | * error a negative value will be returned. |
| 521 | * |
| 522 | * The caller should not free or modify the returned pointer, as it is |
| 523 | * owned by the cache. |
| 524 | */ |
| 525 | RESULT_MUST_BE_USED |
| 526 | int git_configset_get_value_multi(struct config_set *cs, const char *key, |
| 527 | const struct string_list **dest); |
| 528 | |
| 529 | /** |
| 530 | * A validation wrapper for git_configset_get_value_multi() which does |
| 531 | * for it what git_configset_get_string() does for |
| 532 | * git_configset_get_value(). |
| 533 | * |
| 534 | * The configuration syntax allows for "[section] key", which will |
| 535 | * give us a NULL entry in the "struct string_list", as opposed to |
| 536 | * "[section] key =" which is the empty string. Most users of the API |
| 537 | * are not prepared to handle NULL in a "struct string_list". |
| 538 | */ |
| 539 | int git_configset_get_string_multi(struct config_set *cs, const char *key, |
| 540 | const struct string_list **dest); |
| 541 | |
| 542 | /** |
| 543 | * Clears `config_set` structure, removes all saved variable-value pairs. |
| 544 | */ |
| 545 | void git_configset_clear(struct config_set *cs); |
| 546 | |
| 547 | /* |
| 548 | * These functions return 1 if not found, and 0 if found, leaving the found |
| 549 | * value in the 'dest' pointer. |
| 550 | */ |
| 551 | |
| 552 | /** |
| 553 | * git_configset_get() returns negative values on error, see |
| 554 | * repo_config_get() below. |
| 555 | */ |
| 556 | RESULT_MUST_BE_USED |
| 557 | int git_configset_get(struct config_set *cs, const char *key); |
| 558 | |
| 559 | /* |
| 560 | * Finds the highest-priority value for the configuration variable `key` |
| 561 | * and config set `cs`, stores the pointer to it in `value` and returns 0. |
| 562 | * When the configuration variable `key` is not found, returns 1 without |
| 563 | * touching `value`. The caller should not free or modify `value`, as it |
| 564 | * is owned by the cache. |
| 565 | */ |
| 566 | int git_configset_get_value(struct config_set *cs, const char *key, |
| 567 | const char **dest, struct key_value_info *kvi); |
| 568 | |
| 569 | int git_configset_get_string(struct config_set *cs, const char *key, char **dest); |
| 570 | int git_configset_get_int(struct config_set *cs, const char *key, int *dest); |
| 571 | int git_configset_get_uint(struct config_set *cs, const char *key, unsigned int *dest); |
| 572 | int git_configset_get_ulong(struct config_set *cs, const char *key, unsigned long *dest); |
| 573 | int git_configset_get_bool(struct config_set *cs, const char *key, int *dest); |
| 574 | int git_configset_get_bool_or_int(struct config_set *cs, const char *key, int *is_bool, int *dest); |
| 575 | int git_configset_get_maybe_bool(struct config_set *cs, const char *key, int *dest); |
| 576 | |
| 577 | /** |
| 578 | * Run only the discover part of the repo_config_get_*() functions |
| 579 | * below, in addition to 1 if not found, returns negative values on |
| 580 | * error (e.g. if the key itself is invalid). |
| 581 | */ |
| 582 | int repo_config_get_pathname(struct repository *repo, |
| 583 | const char *key, char **dest); |
| 584 | |
| 585 | /* |
| 586 | * Functions for reading protected config. By definition, protected |
| 587 | * config ignores repository config, so these do not take a `struct |
| 588 | * repository` parameter. |
| 589 | */ |
| 590 | void git_protected_config(config_fn_t fn, void *data); |
| 591 | |
| 592 | /** |
| 593 | * Querying For Specific Variables |
| 594 | * ------------------------------- |
| 595 | * |
| 596 | * For programs wanting to query for specific variables in a non-callback |
| 597 | * manner, the config API provides two functions `repo_config_get_value` |
| 598 | * and `repo_config_get_value_multi`. They both read values from an internal |
| 599 | * cache generated previously from reading the config files. |
| 600 | * |
| 601 | * For those repo_config_get*() functions that aren't documented, |
| 602 | * consult the corresponding repo_config_get*() function's |
| 603 | * documentation. |
| 604 | */ |
| 605 | |
| 606 | RESULT_MUST_BE_USED |
| 607 | int repo_config_get(struct repository *r, const char *key); |
| 608 | |
| 609 | /** |
| 610 | * Finds the highest-priority value for the configuration variable `key`, |
| 611 | * stores the pointer to it in `value` and returns 0. When the |
| 612 | * configuration variable `key` is not found, returns 1 without touching |
| 613 | * `value`. The caller should not free or modify `value`, as it is owned |
| 614 | * by the cache. |
| 615 | */ |
| 616 | int repo_config_get_value(struct repository *r, const char *key, const char **value); |
| 617 | |
| 618 | /** |
| 619 | * Finds and returns the value list, sorted in order of increasing priority |
| 620 | * for the configuration variable `key`. When the configuration variable |
| 621 | * `key` is not found, returns 1 without touching `value`. |
| 622 | * |
| 623 | * The caller should not free or modify the returned pointer, as it is |
| 624 | * owned by the cache. |
| 625 | */ |
| 626 | RESULT_MUST_BE_USED |
| 627 | int repo_config_get_value_multi(struct repository *r, const char *key, |
| 628 | const struct string_list **dest); |
| 629 | RESULT_MUST_BE_USED |
| 630 | int repo_config_get_string_multi(struct repository *r, const char *key, |
| 631 | const struct string_list **dest); |
| 632 | |
| 633 | /** |
| 634 | * Resets and invalidates the config cache. |
| 635 | */ |
| 636 | void repo_config_clear(struct repository *repo); |
| 637 | |
| 638 | /** |
| 639 | * Allocates and copies the retrieved string into the `dest` parameter for |
| 640 | * the configuration variable `key`; if NULL string is given, prints an |
| 641 | * error message and returns -1. When the configuration variable `key` is |
| 642 | * not found, returns 1 without touching `dest`. |
| 643 | */ |
| 644 | int repo_config_get_string(struct repository *r, const char *key, char **dest); |
| 645 | |
| 646 | /** |
| 647 | * Similar to `repo_config_get_string`, but does not allocate any new |
| 648 | * memory; on success `dest` will point to memory owned by the config |
| 649 | * machinery, which could be invalidated if it is discarded and reloaded. |
| 650 | */ |
| 651 | int repo_config_get_string_tmp(struct repository *r, |
| 652 | const char *key, const char **dest); |
| 653 | |
| 654 | /** |
| 655 | * Finds and parses the value to an integer for the configuration variable |
| 656 | * `key`. Dies on error; otherwise, stores the value of the parsed integer in |
| 657 | * `dest` and returns 0. When the configuration variable `key` is not found, |
| 658 | * returns 1 without touching `dest`. |
| 659 | */ |
| 660 | int repo_config_get_int(struct repository *r, const char *key, int *dest); |
| 661 | |
| 662 | /** |
| 663 | * Similar to `repo_config_get_int` but for unsigned ints. |
| 664 | */ |
| 665 | int repo_config_get_uint(struct repository *r, |
| 666 | const char *key, unsigned int *dest); |
| 667 | |
| 668 | /** |
| 669 | * Similar to `repo_config_get_int` but for unsigned longs. |
| 670 | */ |
| 671 | int repo_config_get_ulong(struct repository *r, |
| 672 | const char *key, unsigned long *dest); |
| 673 | |
| 674 | /** |
| 675 | * Finds and parses the value into a boolean value, for the configuration |
| 676 | * variable `key` respecting keywords like "true" and "false". Integer |
| 677 | * values are converted into true/false values (when they are non-zero or |
| 678 | * zero, respectively). Other values cause a die(). If parsing is successful, |
| 679 | * stores the value of the parsed result in `dest` and returns 0. When the |
| 680 | * configuration variable `key` is not found, returns 1 without touching |
| 681 | * `dest`. |
| 682 | */ |
| 683 | int repo_config_get_bool(struct repository *r, const char *key, int *dest); |
| 684 | |
| 685 | /** |
| 686 | * Similar to `repo_config_get_bool`, except that integers are copied as-is, |
| 687 | * and `is_bool` flag is unset. |
| 688 | */ |
| 689 | int repo_config_get_bool_or_int(struct repository *r, const char *key, |
| 690 | int *is_bool, int *dest); |
| 691 | |
| 692 | /** |
| 693 | * Similar to `repo_config_get_bool`, except that it returns -1 on error |
| 694 | * rather than dying. |
| 695 | */ |
| 696 | int repo_config_get_maybe_bool(struct repository *r, |
| 697 | const char *key, int *dest); |
| 698 | |
| 699 | int repo_config_get_index_threads(struct repository *r, int *dest); |
| 700 | int repo_config_get_split_index(struct repository *r); |
| 701 | int repo_config_get_max_percent_split_change(struct repository *r); |
| 702 | |
| 703 | /* This dies if the configured or default date is in the future */ |
| 704 | int repo_config_get_expiry(struct repository *r, const char *key, char **output); |
| 705 | |
| 706 | /* parse either "this many days" integer, or "5.days.ago" approxidate */ |
| 707 | int repo_config_get_expiry_in_days(struct repository *r, const char *key, |
| 708 | timestamp_t *, timestamp_t now); |
| 709 | |
| 710 | /** |
| 711 | * First prints the error message specified by the caller in `err` and then |
| 712 | * dies printing the line number and the file name of the highest priority |
| 713 | * value for the configuration variable `key`. |
| 714 | */ |
| 715 | NORETURN void git_die_config(struct repository *r, const char *key, const char *err, ...) |
| 716 | __attribute__((format(printf, 3, 4))); |
| 717 | |
| 718 | /** |
| 719 | * Helper function which formats the die error message according to the |
| 720 | * parameters entered. Used by `git_die_config()`. It can be used by callers |
| 721 | * handling `repo_config_get_value_multi()` to print the correct error message |
| 722 | * for the desired value. |
| 723 | */ |
| 724 | NORETURN void git_die_config_linenr(const char *key, const char *filename, int linenr); |
| 725 | |
| 726 | #define LOOKUP_CONFIG(mapping, var) \ |
| 727 | lookup_config(mapping, ARRAY_SIZE(mapping), var) |
| 728 | int lookup_config(const char **mapping, int nr_mapping, const char *var); |
| 729 | |
| 730 | #endif /* CONFIG_H */ |