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 on Windows, for compatibility with portable git */
  33         GIT_CONFIG_LEVEL_PROGRAMDATA = 1,
  34
  35         /** System-wide configuration file; /etc/gitconfig on Linux systems */
  36         GIT_CONFIG_LEVEL_SYSTEM = 2,
  37
  38         /** XDG compatible configuration file; typically ~/.config/git/config */
  39         GIT_CONFIG_LEVEL_XDG = 3,
  40
  41         /** User-specific configuration file (also called Global configuration
  42          * file); typically ~/.gitconfig
  43          */
  44         GIT_CONFIG_LEVEL_GLOBAL = 4,
  45
  46         /** Repository specific configuration file; $WORK_DIR/.git/config on
  47          * non-bare repos
  48          */
  49         GIT_CONFIG_LEVEL_LOCAL = 5,
  50
  51         /** Application specific configuration file; freely defined by applications
  52          */
  53         GIT_CONFIG_LEVEL_APP = 6,
  54
  55         /** Represents the highest level available config file (i.e. the most
  56          * specific config file available that actually is loaded)
  57          */
  58         GIT_CONFIG_HIGHEST_LEVEL = -1,
  59 } git_config_level_t;
  60
  61 /**
  62  * An entry in a configuration file
  63  */
  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 */
  71 } git_config_entry;
  72
  73 /**
  74  * Free a config entry
  75  */
  76 GIT_EXTERN(void) git_config_entry_free(git_config_entry *);
  77
  78 /**
  79  * A config enumeration callback
  80  *
  81  * @param entry the entry currently being enumerated
  82  * @param payload a user-specified pointer
  83  */
  84 typedef int GIT_CALLBACK(git_config_foreach_cb)(const git_config_entry *entry, void *payload);
  85
  86 /**
  87  * An opaque structure for a configuration iterator
  88  */
  89 typedef struct git_config_iterator git_config_iterator;
  90
  91 /**
  92  * Config var type
  93  */
  94 typedef enum {
  95         GIT_CONFIGMAP_FALSE = 0,
  96         GIT_CONFIGMAP_TRUE = 1,
  97         GIT_CONFIGMAP_INT32,
  98         GIT_CONFIGMAP_STRING
  99 } git_configmap_t;
 100
 101 /**
 102  * Mapping from config variables to values.
 103  */
 104 typedef struct {
 105         git_configmap_t type;
 106         const char *str_match;
 107         int map_value;
 108 } git_configmap;
 109
 110 /**
 111  * Locate the path to the global configuration file
 112  *
 113  * The user or global configuration file is usually
 114  * located in `$HOME/.gitconfig`.
 115  *
 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.
 120  *
 121  * This method will not guess the path to the xdg compatible
 122  * config file (.config/git/config).
 123  *
 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`.
 126  */
 127 GIT_EXTERN(int) git_config_find_global(git_buf *out);
 128
 129 /**
 130  * Locate the path to the global xdg compatible configuration file
 131  *
 132  * The xdg compatible configuration file is usually
 133  * located in `$HOME/.config/git/config`.
 134  *
 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.
 139  *
 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`.
 143  */
 144 GIT_EXTERN(int) git_config_find_xdg(git_buf *out);
 145
 146 /**
 147  * Locate the path to the system configuration file
 148  *
 149  * If /etc/gitconfig doesn't exist, it will look for
 150  * %PROGRAMFILES%\Git\etc\gitconfig.
 151  *
 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`.
 155  */
 156 GIT_EXTERN(int) git_config_find_system(git_buf *out);
 157
 158 /**
 159  * Locate the path to the configuration file in ProgramData
 160  *
 161  * Look for the file in %PROGRAMDATA%\Git\config used by portable git.
 162  *
 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`.
 166  */
 167 GIT_EXTERN(int) git_config_find_programdata(git_buf *out);
 168
 169 /**
 170  * Open the global, XDG and system configuration files
 171  *
 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.
 175  *
 176  * @param out Pointer to store the config instance
 177  * @return 0 or an error code
 178  */
 179 GIT_EXTERN(int) git_config_open_default(git_config **out);
 180
 181 /**
 182  * Allocate a new configuration object
 183  *
 184  * This object is empty, so you have to add a file to it before you
 185  * can do anything with it.
 186  *
 187  * @param out pointer to the new configuration
 188  * @return 0 or an error code
 189  */
 190 GIT_EXTERN(int) git_config_new(git_config **out);
 191
 192 /**
 193  * Add an on-disk config file instance to an existing config
 194  *
 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).
 198  *
 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.
 201  *
 202  * Note that the configuration object will free the file
 203  * automatically.
 204  *
 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).
 208  *
 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
 218  */
 219 GIT_EXTERN(int) git_config_add_file_ondisk(
 220         git_config *cfg,
 221         const char *path,
 222         git_config_level_t level,
 223         const git_repository *repo,
 224         int force);
 225
 226 /**
 227  * Create a new config instance containing a single on-disk file
 228  *
 229  * This method is a simple utility wrapper for the following sequence
 230  * of calls:
 231  *      - git_config_new
 232  *      - git_config_add_file_ondisk
 233  *
 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
 237  */
 238 GIT_EXTERN(int) git_config_open_ondisk(git_config **out, const char *path);
 239
 240 /**
 241  * Build a single-level focused config object from a multi-level one.
 242  *
 243  * The returned config object can be used to perform get/set/delete operations
 244  * on a single specific level.
 245  *
 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
 248  * instance.
 249  *
 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
 255  */
 256 GIT_EXTERN(int) git_config_open_level(
 257         git_config **out,
 258         const git_config *parent,
 259         git_config_level_t level);
 260
 261 /**
 262  * Open the global/XDG configuration file according to git's rules
 263  *
 264  * Git allows you to store your global configuration at
 265  * `$HOME/.gitconfig` or `$XDG_CONFIG_HOME/git/config`. For backwards
 266  * compatibility, the XDG file shouldn't be used unless the use has
 267  * created it explicitly. With this function you'll open the correct
 268  * one to write to.
 269  *
 270  * @param out pointer in which to store the config object
 271  * @param config the config object in which to look
 272  */
 273 GIT_EXTERN(int) git_config_open_global(git_config **out, git_config *config);
 274
 275 /**
 276  * Create a snapshot of the configuration
 277  *
 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).
 281  *
 282  * The string returned when querying such a config object is valid
 283  * until it is freed.
 284  *
 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
 288  */
 289 GIT_EXTERN(int) git_config_snapshot(git_config **out, git_config *config);
 290
 291 /**
 292  * Free the configuration and its associated memory and files
 293  *
 294  * @param cfg the configuration to free
 295  */
 296 GIT_EXTERN(void) git_config_free(git_config *cfg);
 297
 298 /**
 299  * Get the git_config_entry of a config variable.
 300  *
 301  * Free the git_config_entry after use with `git_config_entry_free()`.
 302  *
 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
 307  */
 308 GIT_EXTERN(int) git_config_get_entry(
 309         git_config_entry **out,
 310         const git_config *cfg,
 311         const char *name);
 312
 313 /**
 314  * Get the value of an integer config variable.
 315  *
 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.
 319  *
 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
 324  */
 325 GIT_EXTERN(int) git_config_get_int32(int32_t *out, const git_config *cfg, const char *name);
 326
 327 /**
 328  * Get the value of a long integer config variable.
 329  *
 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.
 333  *
 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
 338  */
 339 GIT_EXTERN(int) git_config_get_int64(int64_t *out, const git_config *cfg, const char *name);
 340
 341 /**
 342  * Get the value of a boolean config variable.
 343  *
 344  * This function uses the usual C convention of 0 being false and
 345  * anything else true.
 346  *
 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.
 350  *
 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
 355  */
 356 GIT_EXTERN(int) git_config_get_bool(int *out, const git_config *cfg, const char *name);
 357
 358 /**
 359  * Get the value of a path config variable.
 360  *
 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()`.
 364  *
 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.
 368  *
 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
 373  */
 374 GIT_EXTERN(int) git_config_get_path(git_buf *out, const git_config *cfg, const char *name);
 375
 376 /**
 377  * Get the value of a string config variable.
 378  *
 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.
 382  *
 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.
 386  *
 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
 391  */
 392 GIT_EXTERN(int) git_config_get_string(const char **out, const git_config *cfg, const char *name);
 393
 394 /**
 395  * Get the value of a string config variable.
 396  *
 397  * The value of the config will be copied into the buffer.
 398  *
 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.
 402  *
 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
 407  */
 408 GIT_EXTERN(int) git_config_get_string_buf(git_buf *out, const git_config *cfg, const char *name);
 409
 410 /**
 411  * Get each value of a multivar in a foreach callback
 412  *
 413  * The callback will be called on each variable found
 414  *
 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.
 418  *
 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
 425  */
 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);
 427
 428 /**
 429  * Get each value of a multivar
 430  *
 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.
 434  *
 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
 440  */
 441 GIT_EXTERN(int) git_config_multivar_iterator_new(git_config_iterator **out, const git_config *cfg, const char *name, const char *regexp);
 442
 443 /**
 444  * Return the current entry and advance the iterator
 445  *
 446  * The pointers returned by this function are valid until the iterator
 447  * is freed.
 448  *
 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
 452  */
 453 GIT_EXTERN(int) git_config_next(git_config_entry **entry, git_config_iterator *iter);
 454
 455 /**
 456  * Free a config iterator
 457  *
 458  * @param iter the iterator to free
 459  */
 460 GIT_EXTERN(void) git_config_iterator_free(git_config_iterator *iter);
 461
 462 /**
 463  * Set the value of an integer config variable in the config file
 464  * with the highest level (usually the local one).
 465  *
 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
 470  */
 471 GIT_EXTERN(int) git_config_set_int32(git_config *cfg, const char *name, int32_t value);
 472
 473 /**
 474  * Set the value of a long integer config variable in the config file
 475  * with the highest level (usually the local one).
 476  *
 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
 481  */
 482 GIT_EXTERN(int) git_config_set_int64(git_config *cfg, const char *name, int64_t value);
 483
 484 /**
 485  * Set the value of a boolean config variable in the config file
 486  * with the highest level (usually the local one).
 487  *
 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
 492  */
 493 GIT_EXTERN(int) git_config_set_bool(git_config *cfg, const char *name, int value);
 494
 495 /**
 496  * Set the value of a string config variable in the config file
 497  * with the highest level (usually the local one).
 498  *
 499  * A copy of the string is made and the user is free to use it
 500  * afterwards.
 501  *
 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
 506  */
 507 GIT_EXTERN(int) git_config_set_string(git_config *cfg, const char *name, const char *value);
 508
 509 /**
 510  * Set a multivar in the local config file.
 511  *
 512  * The regular expression is applied case-sensitively on the value.
 513  *
 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.
 518  */
 519 GIT_EXTERN(int) git_config_set_multivar(git_config *cfg, const char *name, const char *regexp, const char *value);
 520
 521 /**
 522  * Delete a config variable from the config file
 523  * with the highest level (usually the local one).
 524  *
 525  * @param cfg the configuration
 526  * @param name the variable to delete
 527  */
 528 GIT_EXTERN(int) git_config_delete_entry(git_config *cfg, const char *name);
 529
 530 /**
 531  * Deletes one or several entries from a multivar in the local config file.
 532  *
 533  * The regular expression is applied case-sensitively on the value.
 534  *
 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
 538  *
 539  * @return 0 or an error code
 540  */
 541 GIT_EXTERN(int) git_config_delete_multivar(git_config *cfg, const char *name, const char *regexp);
 542
 543 /**
 544  * Perform an operation on each config variable.
 545  *
 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.
 550  *
 551  * The pointers passed to the callback are only valid as long as the
 552  * iteration is ongoing.
 553  *
 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
 558  */
 559 GIT_EXTERN(int) git_config_foreach(
 560         const git_config *cfg,
 561         git_config_foreach_cb callback,
 562         void *payload);
 563
 564 /**
 565  * Iterate over all the config variables
 566  *
 567  * Use `git_config_next` to advance the iteration and
 568  * `git_config_iterator_free` when done.
 569  *
 570  * @param out pointer to store the iterator
 571  * @param cfg where to ge the variables from
 572  */
 573 GIT_EXTERN(int) git_config_iterator_new(git_config_iterator **out, const git_config *cfg);
 574
 575 /**
 576  * Iterate over all the config variables whose name matches a pattern
 577  *
 578  * Use `git_config_next` to advance the iteration and
 579  * `git_config_iterator_free` when done.
 580  *
 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.
 584  *
 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
 588  */
 589 GIT_EXTERN(int) git_config_iterator_glob_new(git_config_iterator **out, const git_config *cfg, const char *regexp);
 590
 591 /**
 592  * Perform an operation on each config variable matching a regular expression.
 593  *
 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
 596  * callback.
 597  *
 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.
 601  *
 602  * The regular expression is applied case-sensitively on the normalized form of
 603  * the variable name: the case-insensitive parts are lower-case.
 604  *
 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
 610  */
 611 GIT_EXTERN(int) git_config_foreach_match(
 612         const git_config *cfg,
 613         const char *regexp,
 614         git_config_foreach_cb callback,
 615         void *payload);
 616
 617 /**
 618  * Query the value of a config variable and return it mapped to
 619  * an integer constant.
 620  *
 621  * This is a helper method to easily map different possible values
 622  * to a variable to integer constants that easily identify them.
 623  *
 624  * A mapping array looks as follows:
 625  *
 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}};
 631  *
 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.
 634  *
 635  * The same thing applies for any "true" value such as "true", "yes" or "1", storing
 636  * the `GIT_AUTO_CRLF_TRUE` variable.
 637  *
 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".
 640  *
 641  * If not a single match can be made to store in `out`, an error code will be
 642  * returned.
 643  *
 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
 650  */
 651 GIT_EXTERN(int) git_config_get_mapped(
 652         int *out,
 653         const git_config *cfg,
 654         const char *name,
 655         const git_configmap *maps,
 656         size_t map_n);
 657
 658 /**
 659  * Maps a string value to an integer constant
 660  *
 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
 665  */
 666 GIT_EXTERN(int) git_config_lookup_map_value(
 667         int *out,
 668         const git_configmap *maps,
 669         size_t map_n,
 670         const char *value);
 671
 672 /**
 673  * Parse a string value as a bool.
 674  *
 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
 678  *
 679  * @param out place to store the result of the parsing
 680  * @param value value to parse
 681  */
 682 GIT_EXTERN(int) git_config_parse_bool(int *out, const char *value);
 683
 684 /**
 685  * Parse a string value as an int32.
 686  *
 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.
 690  *
 691  * @param out place to store the result of the parsing
 692  * @param value value to parse
 693  */
 694 GIT_EXTERN(int) git_config_parse_int32(int32_t *out, const char *value);
 695
 696 /**
 697  * Parse a string value as an int64.
 698  *
 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.
 702  *
 703  * @param out place to store the result of the parsing
 704  * @param value value to parse
 705  */
 706 GIT_EXTERN(int) git_config_parse_int64(int64_t *out, const char *value);
 707
 708 /**
 709  * Parse a string value as a path.
 710  *
 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()`.
 714  *
 715  * If the value does not begin with a tilde, the input will be
 716  * returned.
 717  *
 718  * @param out placae to store the result of parsing
 719  * @param value the path to evaluate
 720  */
 721 GIT_EXTERN(int) git_config_parse_path(git_buf *out, const char *value);
 722
 723 /**
 724  * Perform an operation on each config variable in a given config backend,
 725  * matching a regular expression.
 726  *
 727  * This behaves like `git_config_foreach_match` except that only config
 728  * entries from the given backend entry are enumerated.
 729  *
 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.
 733  *
 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
 738  */
 739 GIT_EXTERN(int) git_config_backend_foreach_match(
 740         git_config_backend *backend,
 741         const char *regexp,
 742         git_config_foreach_cb callback,
 743         void *payload);
 744
 745
 746 /**
 747  * Lock the backend with the highest priority
 748  *
 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.
 752  *
 753  * You can apply the changes by calling `git_transaction_commit()`
 754  * before freeing the transaction. Either of these actions will unlock
 755  * the config.
 756  *
 757  * @param tx the resulting transaction, use this to commit or undo the
 758  * changes
 759  * @param cfg the configuration in which to lock
 760  * @return 0 or an error code
 761  */
 762 GIT_EXTERN(int) git_config_lock(git_transaction **tx, git_config *cfg);
 763
 764 /** @} */
 765 GIT_END_DECL
 766 #endif