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