2 * Copyright (C) the libgit2 contributors. All rights reserved.
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.
7 #ifndef INCLUDE_git_config_h__
8 #define INCLUDE_git_config_h__
16 * @brief Git config management routines
17 * @defgroup git_config Git config management routines
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.
28 * git_config_open_default() and git_repository_config() honor those
29 * priority levels as well.
32 /** System-wide on Windows, for compatibility with portable git */
33 GIT_CONFIG_LEVEL_PROGRAMDATA
= 1,
35 /** System-wide configuration file; /etc/gitconfig on Linux systems */
36 GIT_CONFIG_LEVEL_SYSTEM
= 2,
38 /** XDG compatible configuration file; typically ~/.config/git/config */
39 GIT_CONFIG_LEVEL_XDG
= 3,
41 /** User-specific configuration file (also called Global configuration
42 * file); typically ~/.gitconfig
44 GIT_CONFIG_LEVEL_GLOBAL
= 4,
46 /** Repository specific configuration file; $WORK_DIR/.git/config on
49 GIT_CONFIG_LEVEL_LOCAL
= 5,
51 /** Application specific configuration file; freely defined by applications
53 GIT_CONFIG_LEVEL_APP
= 6,
55 /** Represents the highest level available config file (i.e. the most
56 * specific config file available that actually is loaded)
58 GIT_CONFIG_HIGHEST_LEVEL
= -1,
62 * An entry in a configuration file
64 typedef struct git_config_entry
{
65 const char *name
; /**< Name of the entry (normalised) */
66 const char *value
; /**< String value of the entry */
67 unsigned int include_depth
; /**< Depth of includes where this variable was found */
68 git_config_level_t level
; /**< Which config file this was found in */
69 void GIT_CALLBACK(free
)(struct git_config_entry
*entry
); /**< Free function for this entry */
70 void *payload
; /**< Opaque value for the free function. Do not read or write */
76 GIT_EXTERN(void) git_config_entry_free(git_config_entry
*);
79 * A config enumeration callback
81 * @param entry the entry currently being enumerated
82 * @param payload a user-specified pointer
84 typedef int GIT_CALLBACK(git_config_foreach_cb
)(const git_config_entry
*entry
, void *payload
);
87 * An opaque structure for a configuration iterator
89 typedef struct git_config_iterator git_config_iterator
;
95 GIT_CONFIGMAP_FALSE
= 0,
96 GIT_CONFIGMAP_TRUE
= 1,
102 * Mapping from config variables to values.
105 git_configmap_t type
;
106 const char *str_match
;
111 * Locate the path to the global configuration file
113 * The user or global configuration file is usually
114 * located in `$HOME/.gitconfig`.
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.
121 * This method will not guess the path to the xdg compatible
122 * config file (.config/git/config).
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`.
127 GIT_EXTERN(int) git_config_find_global(git_buf
*out
);
130 * Locate the path to the global xdg compatible configuration file
132 * The xdg compatible configuration file is usually
133 * located in `$HOME/.config/git/config`.
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
138 * xdg compatible configuration file.
140 * @param out Pointer to a user-allocated git_buf in which to store the path
141 * @return 0 if a xdg compatible configuration file has been
142 * found. Its path will be stored in `out`.
144 GIT_EXTERN(int) git_config_find_xdg(git_buf
*out
);
147 * Locate the path to the system configuration file
149 * If /etc/gitconfig doesn't exist, it will look for
150 * %PROGRAMFILES%\Git\etc\gitconfig.
152 * @param out Pointer to a user-allocated git_buf in which to store the path
153 * @return 0 if a system configuration file has been
154 * found. Its path will be stored in `out`.
156 GIT_EXTERN(int) git_config_find_system(git_buf
*out
);
159 * Locate the path to the configuration file in ProgramData
161 * Look for the file in %PROGRAMDATA%\Git\config used by portable git.
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`.
167 GIT_EXTERN(int) git_config_find_programdata(git_buf
*out
);
170 * Open the global, XDG and system configuration files
172 * Utility wrapper that finds the global, XDG and system configuration files
173 * and opens them into a single prioritized config object that can be
174 * used when accessing default config data outside a repository.
176 * @param out Pointer to store the config instance
177 * @return 0 or an error code
179 GIT_EXTERN(int) git_config_open_default(git_config
**out
);
182 * Allocate a new configuration object
184 * This object is empty, so you have to add a file to it before you
185 * can do anything with it.
187 * @param out pointer to the new configuration
188 * @return 0 or an error code
190 GIT_EXTERN(int) git_config_new(git_config
**out
);
193 * Add an on-disk config file instance to an existing config
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).
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.
202 * Note that the configuration object will free the file
205 * Further queries on this config object will access each
206 * of the config file instances in order (instances with
207 * a higher priority level will be accessed first).
209 * @param cfg the configuration to add the file to
210 * @param path path to the configuration file to add
211 * @param level the priority level of the backend
212 * @param force replace config file at the given priority level
213 * @param repo optional repository to allow parsing of
214 * conditional includes
215 * @return 0 on success, GIT_EEXISTS when adding more than one file
216 * for a given priority level (and force_replace set to 0),
217 * GIT_ENOTFOUND when the file doesn't exist or error code
219 GIT_EXTERN(int) git_config_add_file_ondisk(
222 git_config_level_t level
,
223 const git_repository
*repo
,
227 * Create a new config instance containing a single on-disk file
229 * This method is a simple utility wrapper for the following sequence
232 * - git_config_add_file_ondisk
234 * @param out The configuration instance to create
235 * @param path Path to the on-disk file to open
236 * @return 0 on success, or an error code
238 GIT_EXTERN(int) git_config_open_ondisk(git_config
**out
, const char *path
);
241 * Build a single-level focused config object from a multi-level one.
243 * The returned config object can be used to perform get/set/delete operations
244 * on a single specific level.
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
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
253 * @return 0, GIT_ENOTFOUND if the passed level cannot be found in the
254 * multi-level parent config, or an error code
256 GIT_EXTERN(int) git_config_open_level(
258 const git_config
*parent
,
259 git_config_level_t level
);
262 * Open the global/XDG configuration file according to git's rules
264 * Git allows you to store your global configuration at
265 * `$HOME/.gitconfig` or `$XDG_CONFIG_HOME/git/config`. For backwards
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
270 * @param out pointer in which to store the config object
271 * @param config the config object in which to look
273 GIT_EXTERN(int) git_config_open_global(git_config
**out
, git_config
*config
);
276 * Create a snapshot of the configuration
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).
282 * The string returned when querying such a config object is valid
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
289 GIT_EXTERN(int) git_config_snapshot(git_config
**out
, git_config
*config
);
292 * Free the configuration and its associated memory and files
294 * @param cfg the configuration to free
296 GIT_EXTERN(void) git_config_free(git_config
*cfg
);
299 * Get the git_config_entry of a config variable.
301 * Free the git_config_entry after use with `git_config_entry_free()`.
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
308 GIT_EXTERN(int) git_config_get_entry(
309 git_config_entry
**out
,
310 const git_config
*cfg
,
314 * Get the value of an integer config variable.
316 * All config files will be looked into, in the order of their
317 * defined level. A higher level means a higher priority. The
318 * first occurrence of the variable will be returned here.
320 * @param out pointer to the variable where the value should be stored
321 * @param cfg where to look for the variable
322 * @param name the variable's name
323 * @return 0 or an error code
325 GIT_EXTERN(int) git_config_get_int32(int32_t *out
, const git_config
*cfg
, const char *name
);
328 * Get the value of a long integer config variable.
330 * All config files will be looked into, in the order of their
331 * defined level. A higher level means a higher priority. The
332 * first occurrence of the variable will be returned here.
334 * @param out pointer to the variable where the value should be stored
335 * @param cfg where to look for the variable
336 * @param name the variable's name
337 * @return 0 or an error code
339 GIT_EXTERN(int) git_config_get_int64(int64_t *out
, const git_config
*cfg
, const char *name
);
342 * Get the value of a boolean config variable.
344 * This function uses the usual C convention of 0 being false and
345 * anything else true.
347 * All config files will be looked into, in the order of their
348 * defined level. A higher level means a higher priority. The
349 * first occurrence of the variable will be returned here.
351 * @param out pointer to the variable where the value should be stored
352 * @param cfg where to look for the variable
353 * @param name the variable's name
354 * @return 0 or an error code
356 GIT_EXTERN(int) git_config_get_bool(int *out
, const git_config
*cfg
, const char *name
);
359 * Get the value of a path config variable.
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()`.
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.
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
372 * @return 0 or an error code
374 GIT_EXTERN(int) git_config_get_path(git_buf
*out
, const git_config
*cfg
, const char *name
);
377 * Get the value of a string config variable.
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.
383 * All config files will be looked into, in the order of their
384 * defined level. A higher level means a higher priority. The
385 * first occurrence of the variable will be returned here.
387 * @param out pointer to the string
388 * @param cfg where to look for the variable
389 * @param name the variable's name
390 * @return 0 or an error code
392 GIT_EXTERN(int) git_config_get_string(const char **out
, const git_config
*cfg
, const char *name
);
395 * Get the value of a string config variable.
397 * The value of the config will be copied into the buffer.
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.
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
408 GIT_EXTERN(int) git_config_get_string_buf(git_buf
*out
, const git_config
*cfg
, const char *name
);
411 * Get each value of a multivar in a foreach callback
413 * The callback will be called on each variable found
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.
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
423 * @param callback the function to be called on each value of the variable
424 * @param payload opaque pointer to pass to the callback
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
);
429 * Get each value of a multivar
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.
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
441 GIT_EXTERN(int) git_config_multivar_iterator_new(git_config_iterator
**out
, const git_config
*cfg
, const char *name
, const char *regexp
);
444 * Return the current entry and advance the iterator
446 * The pointers returned by this function are valid until the iterator
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
453 GIT_EXTERN(int) git_config_next(git_config_entry
**entry
, git_config_iterator
*iter
);
456 * Free a config iterator
458 * @param iter the iterator to free
460 GIT_EXTERN(void) git_config_iterator_free(git_config_iterator
*iter
);
463 * Set the value of an integer config variable in the config file
464 * with the highest level (usually the local one).
466 * @param cfg where to look for the variable
467 * @param name the variable's name
468 * @param value Integer value for the variable
469 * @return 0 or an error code
471 GIT_EXTERN(int) git_config_set_int32(git_config
*cfg
, const char *name
, int32_t value
);
474 * Set the value of a long integer config variable in the config file
475 * with the highest level (usually the local one).
477 * @param cfg where to look for the variable
478 * @param name the variable's name
479 * @param value Long integer value for the variable
480 * @return 0 or an error code
482 GIT_EXTERN(int) git_config_set_int64(git_config
*cfg
, const char *name
, int64_t value
);
485 * Set the value of a boolean config variable in the config file
486 * with the highest level (usually the local one).
488 * @param cfg where to look for the variable
489 * @param name the variable's name
490 * @param value the value to store
491 * @return 0 or an error code
493 GIT_EXTERN(int) git_config_set_bool(git_config
*cfg
, const char *name
, int value
);
496 * Set the value of a string config variable in the config file
497 * with the highest level (usually the local one).
499 * A copy of the string is made and the user is free to use it
502 * @param cfg where to look for the variable
503 * @param name the variable's name
504 * @param value the string to store.
505 * @return 0 or an error code
507 GIT_EXTERN(int) git_config_set_string(git_config
*cfg
, const char *name
, const char *value
);
510 * Set a multivar in the local config file.
512 * The regular expression is applied case-sensitively on the value.
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.
519 GIT_EXTERN(int) git_config_set_multivar(git_config
*cfg
, const char *name
, const char *regexp
, const char *value
);
522 * Delete a config variable from the config file
523 * with the highest level (usually the local one).
525 * @param cfg the configuration
526 * @param name the variable to delete
528 GIT_EXTERN(int) git_config_delete_entry(git_config
*cfg
, const char *name
);
531 * Deletes one or several entries from a multivar in the local config file.
533 * The regular expression is applied case-sensitively on the value.
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
539 * @return 0 or an error code
541 GIT_EXTERN(int) git_config_delete_multivar(git_config
*cfg
, const char *name
, const char *regexp
);
544 * Perform an operation on each config variable.
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.
548 * If the callback returns a non-zero value, the function stops iterating
549 * and returns that value to the caller.
551 * The pointers passed to the callback are only valid as long as the
552 * iteration is ongoing.
554 * @param cfg where to get the variables from
555 * @param callback the function to call on each variable
556 * @param payload the data to pass to the callback
557 * @return 0 on success, non-zero callback return value, or error code
559 GIT_EXTERN(int) git_config_foreach(
560 const git_config
*cfg
,
561 git_config_foreach_cb callback
,
565 * Iterate over all the config variables
567 * Use `git_config_next` to advance the iteration and
568 * `git_config_iterator_free` when done.
570 * @param out pointer to store the iterator
571 * @param cfg where to ge the variables from
573 GIT_EXTERN(int) git_config_iterator_new(git_config_iterator
**out
, const git_config
*cfg
);
576 * Iterate over all the config variables whose name matches a pattern
578 * Use `git_config_next` to advance the iteration and
579 * `git_config_iterator_free` when done.
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.
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
589 GIT_EXTERN(int) git_config_iterator_glob_new(git_config_iterator
**out
, const git_config
*cfg
, const char *regexp
);
592 * Perform an operation on each config variable matching a regular expression.
594 * This behaves like `git_config_foreach` with an additional filter of a
595 * regular expression that filters which config keys are passed to the
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.
602 * The regular expression is applied case-sensitively on the normalized form of
603 * the variable name: the case-insensitive parts are lower-case.
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
611 GIT_EXTERN(int) git_config_foreach_match(
612 const git_config
*cfg
,
614 git_config_foreach_cb callback
,
618 * Query the value of a config variable and return it mapped to
619 * an integer constant.
621 * This is a helper method to easily map different possible values
622 * to a variable to integer constants that easily identify them.
624 * A mapping array looks as follows:
626 * git_configmap autocrlf_mapping[] = {
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}};
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.
635 * The same thing applies for any "true" value such as "true", "yes" or "1", storing
636 * the `GIT_AUTO_CRLF_TRUE` variable.
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".
641 * If not a single match can be made to store in `out`, an error code will be
644 * @param out place to store the result of the mapping
645 * @param cfg config file to get the variables from
646 * @param name name of the config variable to lookup
647 * @param maps array of `git_configmap` objects specifying the possible mappings
648 * @param map_n number of mapping objects in `maps`
649 * @return 0 on success, error code otherwise
651 GIT_EXTERN(int) git_config_get_mapped(
653 const git_config
*cfg
,
655 const git_configmap
*maps
,
659 * Maps a string value to an integer constant
661 * @param out place to store the result of the parsing
662 * @param maps array of `git_configmap` objects specifying the possible mappings
663 * @param map_n number of mapping objects in `maps`
664 * @param value value to parse
666 GIT_EXTERN(int) git_config_lookup_map_value(
668 const git_configmap
*maps
,
673 * Parse a string value as a bool.
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
679 * @param out place to store the result of the parsing
680 * @param value value to parse
682 GIT_EXTERN(int) git_config_parse_bool(int *out
, const char *value
);
685 * Parse a string value as an int32.
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.
691 * @param out place to store the result of the parsing
692 * @param value value to parse
694 GIT_EXTERN(int) git_config_parse_int32(int32_t *out
, const char *value
);
697 * Parse a string value as an int64.
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.
703 * @param out place to store the result of the parsing
704 * @param value value to parse
706 GIT_EXTERN(int) git_config_parse_int64(int64_t *out
, const char *value
);
709 * Parse a string value as a path.
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()`.
715 * If the value does not begin with a tilde, the input will be
718 * @param out placae to store the result of parsing
719 * @param value the path to evaluate
721 GIT_EXTERN(int) git_config_parse_path(git_buf
*out
, const char *value
);
724 * Perform an operation on each config variable in a given config backend,
725 * matching a regular expression.
727 * This behaves like `git_config_foreach_match` except that only config
728 * entries from the given backend entry are enumerated.
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.
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
739 GIT_EXTERN(int) git_config_backend_foreach_match(
740 git_config_backend
*backend
,
742 git_config_foreach_cb callback
,
747 * Lock the backend with the highest priority
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.
753 * You can apply the changes by calling `git_transaction_commit()`
754 * before freeing the transaction. Either of these actions will unlock
757 * @param tx the resulting transaction, use this to commit or undo the
759 * @param cfg the configuration in which to lock
760 * @return 0 or an error code
762 GIT_EXTERN(int) git_config_lock(git_transaction
**tx
, git_config
*cfg
);