]>
Commit | Line | Data |
---|---|---|
9c3c22e2 JK |
1 | config API |
2 | ========== | |
3 | ||
4 | The config API gives callers a way to access git configuration files | |
5 | (and files which have the same syntax). See linkgit:git-config[1] for a | |
6 | discussion of the config file syntax. | |
7 | ||
8 | General Usage | |
9 | ------------- | |
10 | ||
11 | Config files are parsed linearly, and each variable found is passed to a | |
12 | caller-provided callback function. The callback function is responsible | |
13 | for any actions to be taken on the config option, and is free to ignore | |
d7be1f14 | 14 | some options. It is not uncommon for the configuration to be parsed |
9c3c22e2 | 15 | several times during the run of a git program, with different callbacks |
d7be1f14 | 16 | picking out different variables useful to themselves. |
9c3c22e2 JK |
17 | |
18 | A config callback function takes three parameters: | |
19 | ||
20 | - the name of the parsed variable. This is in canonical "flat" form: the | |
21 | section, subsection, and variable segments will be separated by dots, | |
22 | and the section and variable segments will be all lowercase. E.g., | |
23 | `core.ignorecase`, `diff.SomeType.textconv`. | |
24 | ||
25 | - the value of the found variable, as a string. If the variable had no | |
26 | value specified, the value will be NULL (typically this means it | |
27 | should be interpreted as boolean true). | |
28 | ||
29 | - a void pointer passed in by the caller of the config API; this can | |
30 | contain callback-specific data | |
31 | ||
32 | A config callback should return 0 for success, or -1 if the variable | |
33 | could not be parsed properly. | |
34 | ||
35 | Basic Config Querying | |
36 | --------------------- | |
37 | ||
38 | Most programs will simply want to look up variables in all config files | |
39 | that git knows about, using the normal precedence rules. To do this, | |
40 | call `git_config` with a callback function and void data pointer. | |
41 | ||
42 | `git_config` will read all config sources in order of increasing | |
43 | priority. Thus a callback should typically overwrite previously-seen | |
44 | entries with new ones (e.g., if both the user-wide `~/.gitconfig` and | |
45 | repo-specific `.git/config` contain `color.ui`, the config machinery | |
46 | will first feed the user-wide one to the callback, and then the | |
47 | repo-specific one; by overwriting, the higher-priority repo-specific | |
48 | value is left at the end). | |
49 | ||
d7be1f14 JK |
50 | There is a special version of `git_config` called `git_config_early`. |
51 | This version takes an additional parameter to specify the repository | |
52 | config, instead of having it looked up via `git_path`. This is useful | |
53 | early in a git program before the repository has been found. Unless | |
54 | you're working with early setup code, you probably don't want to use | |
55 | this. | |
9c3c22e2 JK |
56 | |
57 | Reading Specific Files | |
58 | ---------------------- | |
59 | ||
60 | To read a specific file in git-config format, use | |
61 | `git_config_from_file`. This takes the same callback and data parameters | |
62 | as `git_config`. | |
63 | ||
64 | Value Parsing Helpers | |
65 | --------------------- | |
66 | ||
67 | To aid in parsing string values, the config API provides callbacks with | |
68 | a number of helper functions, including: | |
69 | ||
70 | `git_config_int`:: | |
71 | Parse the string to an integer, including unit factors. Dies on error; | |
72 | otherwise, returns the parsed result. | |
73 | ||
74 | `git_config_ulong`:: | |
75 | Identical to `git_config_int`, but for unsigned longs. | |
76 | ||
77 | `git_config_bool`:: | |
78 | Parse a string into a boolean value, respecting keywords like "true" and | |
79 | "false". Integer values are converted into true/false values (when they | |
80 | are non-zero or zero, respectively). Other values cause a die(). If | |
81 | parsing is successful, the return value is the result. | |
82 | ||
83 | `git_config_bool_or_int`:: | |
84 | Same as `git_config_bool`, except that integers are returned as-is, and | |
85 | an `is_bool` flag is unset. | |
86 | ||
87 | `git_config_maybe_bool`:: | |
88 | Same as `git_config_bool`, except that it returns -1 on error rather | |
89 | than dying. | |
90 | ||
91 | `git_config_string`:: | |
92 | Allocates and copies the value string into the `dest` parameter; if no | |
93 | string is given, prints an error message and returns -1. | |
94 | ||
95 | `git_config_pathname`:: | |
96 | Similar to `git_config_string`, but expands `~` or `~user` into the | |
97 | user's home directory when found at the beginning of the path. | |
98 | ||
99 | Writing Config Files | |
100 | -------------------- | |
101 | ||
102 | TODO |