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