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  * Create a snapshot of the configuration
 231  *
 232  * Create a snapshot of the current state of a configuration, which
 233  * allows you to look into a consistent view of the configuration for
 234  * looking up complex values (e.g. a remote, submodule).
 235  *
 236  * The string returned when querying such a config object is valid
 237  * until it is freed.
 238  *
 239  * @param out pointer in which to store the snapshot config object
 240  * @param config configuration to snapshot
 241  * @return 0 or an error code
 242  */
 243 GIT_EXTERN(int) git_config_snapshot(git_config **out, git_config *config);
 244
 245
 246 /**
 247  * Reload changed config files
 248  *
 249  * A config file may be changed on disk out from under the in-memory
 250  * config object.  This function causes us to look for files that have
 251  * been modified since we last loaded them and refresh the config with
 252  * the latest information.
 253  *
 254  * @param cfg The configuration to refresh
 255  * @return 0 or an error code
 256  */
 257 GIT_EXTERN(int) git_config_refresh(git_config *cfg);
 258
 259 /**
 260  * Free the configuration and its associated memory and files
 261  *
 262  * @param cfg the configuration to free
 263  */
 264 GIT_EXTERN(void) git_config_free(git_config *cfg);
 265
 266 /**
 267  * Get the git_config_entry of a config variable.
 268  *
 269  * The git_config_entry is owned by the config and should not be freed by the
 270  * user.
 271
 272  * @param out pointer to the variable git_config_entry
 273  * @param cfg where to look for the variable
 274  * @param name the variable's name
 275  * @return 0 or an error code
 276  */
 277 GIT_EXTERN(int) git_config_get_entry(
 278         const git_config_entry **out,
 279         const git_config *cfg,
 280         const char *name);
 281
 282 /**
 283  * Get the value of an 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 occurence 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_int32(int32_t *out, const git_config *cfg, const char *name);
 295
 296 /**
 297  * Get the value of a long integer config variable.
 298  *
 299  * All config files will be looked into, in the order of their
 300  * defined level. A higher level means a higher priority. The
 301  * first occurrence of the variable will be returned here.
 302  *
 303  * @param out pointer to the variable where the value should be stored
 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_int64(int64_t *out, const git_config *cfg, const char *name);
 309
 310 /**
 311  * Get the value of a boolean config variable.
 312  *
 313  * This function uses the usual C convention of 0 being false and
 314  * anything else true.
 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_bool(int *out, const git_config *cfg, const char *name);
 326
 327 /**
 328  * Get the value of a string config variable.
 329  *
 330  * The string is owned by the variable and should not be freed by the
 331  * user. The pointer will be valid until the next operation on this
 332  * config object.
 333  *
 334  * All config files will be looked into, in the order of their
 335  * defined level. A higher level means a higher priority. The
 336  * first occurrence of the variable will be returned here.
 337  *
 338  * @param out pointer to the variable's value
 339  * @param cfg where to look for the variable
 340  * @param name the variable's name
 341  * @return 0 or an error code
 342  */
 343 GIT_EXTERN(int) git_config_get_string(const char **out, const git_config *cfg, const char *name);
 344
 345 /**
 346  * Get each value of a multivar in a foreach callback
 347  *
 348  * The callback will be called on each variable found
 349  *
 350  * @param cfg where to look for the variable
 351  * @param name the variable's name
 352  * @param regexp regular expression to filter which variables we're
 353  * interested in. Use NULL to indicate all
 354  * @param callback the function to be called on each value of the variable
 355  * @param payload opaque pointer to pass to the callback
 356  */
 357 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);
 358
 359 /**
 360  * Get each value of a multivar
 361  *
 362  * @param out pointer to store the iterator
 363  * @param cfg where to look for the variable
 364  * @param name the variable's name
 365  * @param regexp regular expression to filter which variables we're
 366  * interested in. Use NULL to indicate all
 367  */
 368 GIT_EXTERN(int) git_config_multivar_iterator_new(git_config_iterator **out, const git_config *cfg, const char *name, const char *regexp);
 369
 370 /**
 371  * Return the current entry and advance the iterator
 372  *
 373  * The pointers returned by this function are valid until the iterator
 374  * is freed.
 375  *
 376  * @param entry pointer to store the entry
 377  * @param iter the iterator
 378  * @return 0 or an error code. GIT_ITEROVER if the iteration has completed
 379  */
 380 GIT_EXTERN(int) git_config_next(git_config_entry **entry, git_config_iterator *iter);
 381
 382 /**
 383  * Free a config iterator
 384  *
 385  * @param iter the iterator to free
 386  */
 387 GIT_EXTERN(void) git_config_iterator_free(git_config_iterator *iter);
 388
 389 /**
 390  * Set the value of an integer config variable in the config file
 391  * with the highest level (usually the local one).
 392  *
 393  * @param cfg where to look for the variable
 394  * @param name the variable's name
 395  * @param value Integer value for the variable
 396  * @return 0 or an error code
 397  */
 398 GIT_EXTERN(int) git_config_set_int32(git_config *cfg, const char *name, int32_t value);
 399
 400 /**
 401  * Set the value of a long integer config variable in the config file
 402  * with the highest level (usually the local one).
 403  *
 404  * @param cfg where to look for the variable
 405  * @param name the variable's name
 406  * @param value Long integer value for the variable
 407  * @return 0 or an error code
 408  */
 409 GIT_EXTERN(int) git_config_set_int64(git_config *cfg, const char *name, int64_t value);
 410
 411 /**
 412  * Set the value of a boolean config variable in the config file
 413  * with the highest level (usually the local one).
 414  *
 415  * @param cfg where to look for the variable
 416  * @param name the variable's name
 417  * @param value the value to store
 418  * @return 0 or an error code
 419  */
 420 GIT_EXTERN(int) git_config_set_bool(git_config *cfg, const char *name, int value);
 421
 422 /**
 423  * Set the value of a string config variable in the config file
 424  * with the highest level (usually the local one).
 425  *
 426  * A copy of the string is made and the user is free to use it
 427  * afterwards.
 428  *
 429  * @param cfg where to look for the variable
 430  * @param name the variable's name
 431  * @param value the string to store.
 432  * @return 0 or an error code
 433  */
 434 GIT_EXTERN(int) git_config_set_string(git_config *cfg, const char *name, const char *value);
 435
 436 /**
 437  * Set a multivar in the local config file.
 438  *
 439  * @param cfg where to look for the variable
 440  * @param name the variable's name
 441  * @param regexp a regular expression to indicate which values to replace
 442  * @param value the new value.
 443  */
 444 GIT_EXTERN(int) git_config_set_multivar(git_config *cfg, const char *name, const char *regexp, const char *value);
 445
 446 /**
 447  * Delete a config variable from the config file
 448  * with the highest level (usually the local one).
 449  *
 450  * @param cfg the configuration
 451  * @param name the variable to delete
 452  */
 453 GIT_EXTERN(int) git_config_delete_entry(git_config *cfg, const char *name);
 454
 455 /**
 456  * Deletes one or several entries from a multivar in the local config file.
 457  *
 458  * @param cfg where to look for the variables
 459  * @param name the variable's name
 460  * @param regexp a regular expression to indicate which values to delete
 461  *
 462  * @return 0 or an error code
 463  */
 464 GIT_EXTERN(int) git_config_delete_multivar(git_config *cfg, const char *name, const char *regexp);
 465
 466 /**
 467  * Perform an operation on each config variable.
 468  *
 469  * The callback receives the normalized name and value of each variable
 470  * in the config backend, and the data pointer passed to this function.
 471  * If the callback returns a non-zero value, the function stops iterating
 472  * and returns that value to the caller.
 473  *
 474  * The pointers passed to the callback are only valid as long as the
 475  * iteration is ongoing.
 476  *
 477  * @param cfg where to get the variables from
 478  * @param callback the function to call on each variable
 479  * @param payload the data to pass to the callback
 480  * @return 0 on success, non-zero callback return value, or error code
 481  */
 482 GIT_EXTERN(int) git_config_foreach(
 483         const git_config *cfg,
 484         git_config_foreach_cb callback,
 485         void *payload);
 486
 487 /**
 488  * Iterate over all the config variables
 489  *
 490  * Use `git_config_next` to advance the iteration and
 491  * `git_config_iterator_free` when done.
 492  *
 493  * @param out pointer to store the iterator
 494  * @param cfg where to ge the variables from
 495  */
 496 GIT_EXTERN(int) git_config_iterator_new(git_config_iterator **out, const git_config *cfg);
 497
 498 /**
 499  * Iterate over all the config variables whose name matches a pattern
 500  *
 501  * Use `git_config_next` to advance the iteration and
 502  * `git_config_iterator_free` when done.
 503  *
 504  * @param out pointer to store the iterator
 505  * @param cfg where to ge the variables from
 506  * @param regexp regular expression to match the names
 507  */
 508 GIT_EXTERN(int) git_config_iterator_glob_new(git_config_iterator **out, const git_config *cfg, const char *regexp);
 509
 510 /**
 511  * Perform an operation on each config variable matching a regular expression.
 512  *
 513  * This behaviors like `git_config_foreach` with an additional filter of a
 514  * regular expression that filters which config keys are passed to the
 515  * callback.
 516  *
 517  * The pointers passed to the callback are only valid as long as the
 518  * iteration is ongoing.
 519  *
 520  * @param cfg where to get the variables from
 521  * @param regexp regular expression to match against config names
 522  * @param callback the function to call on each variable
 523  * @param payload the data to pass to the callback
 524  * @return 0 or the return value of the callback which didn't return 0
 525  */
 526 GIT_EXTERN(int) git_config_foreach_match(
 527         const git_config *cfg,
 528         const char *regexp,
 529         git_config_foreach_cb callback,
 530         void *payload);
 531
 532 /**
 533  * Query the value of a config variable and return it mapped to
 534  * an integer constant.
 535  *
 536  * This is a helper method to easily map different possible values
 537  * to a variable to integer constants that easily identify them.
 538  *
 539  * A mapping array looks as follows:
 540  *
 541  *      git_cvar_map autocrlf_mapping[] = {
 542  *              {GIT_CVAR_FALSE, NULL, GIT_AUTO_CRLF_FALSE},
 543  *              {GIT_CVAR_TRUE, NULL, GIT_AUTO_CRLF_TRUE},
 544  *              {GIT_CVAR_STRING, "input", GIT_AUTO_CRLF_INPUT},
 545  *              {GIT_CVAR_STRING, "default", GIT_AUTO_CRLF_DEFAULT}};
 546  *
 547  * On any "false" value for the variable (e.g. "false", "FALSE", "no"), the
 548  * mapping will store `GIT_AUTO_CRLF_FALSE` in the `out` parameter.
 549  *
 550  * The same thing applies for any "true" value such as "true", "yes" or "1", storing
 551  * the `GIT_AUTO_CRLF_TRUE` variable.
 552  *
 553  * Otherwise, if the value matches the string "input" (with case insensitive comparison),
 554  * the given constant will be stored in `out`, and likewise for "default".
 555  *
 556  * If not a single match can be made to store in `out`, an error code will be
 557  * returned.
 558  *
 559  * @param out place to store the result of the mapping
 560  * @param cfg config file to get the variables from
 561  * @param name name of the config variable to lookup
 562  * @param maps array of `git_cvar_map` objects specifying the possible mappings
 563  * @param map_n number of mapping objects in `maps`
 564  * @return 0 on success, error code otherwise
 565  */
 566 GIT_EXTERN(int) git_config_get_mapped(
 567         int *out,
 568         const git_config *cfg,
 569         const char *name,
 570         const git_cvar_map *maps,
 571         size_t map_n);
 572
 573 /**
 574  * Maps a string value to an integer constant
 575  *
 576  * @param out place to store the result of the parsing
 577  * @param maps array of `git_cvar_map` objects specifying the possible mappings
 578  * @param map_n number of mapping objects in `maps`
 579  * @param value value to parse
 580  */
 581 GIT_EXTERN(int) git_config_lookup_map_value(
 582         int *out,
 583         const git_cvar_map *maps,
 584         size_t map_n,
 585         const char *value);
 586
 587 /**
 588  * Parse a string value as a bool.
 589  *
 590  * Valid values for true are: 'true', 'yes', 'on', 1 or any
 591  *  number different from 0
 592  * Valid values for false are: 'false', 'no', 'off', 0
 593  *
 594  * @param out place to store the result of the parsing
 595  * @param value value to parse
 596  */
 597 GIT_EXTERN(int) git_config_parse_bool(int *out, const char *value);
 598
 599 /**
 600  * Parse a string value as an int32.
 601  *
 602  * An optional value suffix of 'k', 'm', or 'g' will
 603  * cause the value to be multiplied by 1024, 1048576,
 604  * or 1073741824 prior to output.
 605  *
 606  * @param out place to store the result of the parsing
 607  * @param value value to parse
 608  */
 609 GIT_EXTERN(int) git_config_parse_int32(int32_t *out, const char *value);
 610
 611 /**
 612  * Parse a string value as an int64.
 613  *
 614  * An optional value suffix of 'k', 'm', or 'g' will
 615  * cause the value to be multiplied by 1024, 1048576,
 616  * or 1073741824 prior to output.
 617  *
 618  * @param out place to store the result of the parsing
 619  * @param value value to parse
 620  */
 621 GIT_EXTERN(int) git_config_parse_int64(int64_t *out, const char *value);
 622
 623
 624 /**
 625  * Perform an operation on each config variable in given config backend
 626  * matching a regular expression.
 627  *
 628  * This behaviors like `git_config_foreach_match` except instead of all config
 629  * entries it just enumerates through the given backend entry.
 630  *
 631  * @param backend where to get the variables from
 632  * @param regexp regular expression to match against config names (can be NULL)
 633  * @param callback the function to call on each variable
 634  * @param payload the data to pass to the callback
 635  */
 636 GIT_EXTERN(int) git_config_backend_foreach_match(
 637         git_config_backend *backend,
 638         const char *regexp,
 639         git_config_foreach_cb callback,
 640         void *payload);
 641
 642
 643 /** @} */
 644 GIT_END_DECL
 645 #endif