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