include/git2/config.h

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