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 | ||
c9b5e2a5 JK |
50 | The `git_config_with_options` function lets the caller examine config |
51 | while adjusting some of the default behavior of `git_config`. It should | |
52 | almost never be used by "regular" git code that is looking up | |
53 | configuration variables. It is intended for advanced callers like | |
54 | `git-config`, which are intentionally tweaking the normal config-lookup | |
9b25a0b5 | 55 | process. It takes two extra parameters: |
c9b5e2a5 JK |
56 | |
57 | `filename`:: | |
58 | If this parameter is non-NULL, it specifies the name of a file to | |
59 | parse for configuration, rather than looking in the usual files. Regular | |
60 | `git_config` defaults to `NULL`. | |
61 | ||
9b25a0b5 JK |
62 | `respect_includes`:: |
63 | Specify whether include directives should be followed in parsed files. | |
64 | Regular `git_config` defaults to `1`. | |
65 | ||
d7be1f14 JK |
66 | There is a special version of `git_config` called `git_config_early`. |
67 | This version takes an additional parameter to specify the repository | |
68 | config, instead of having it looked up via `git_path`. This is useful | |
69 | early in a git program before the repository has been found. Unless | |
70 | you're working with early setup code, you probably don't want to use | |
71 | this. | |
9c3c22e2 JK |
72 | |
73 | Reading Specific Files | |
74 | ---------------------- | |
75 | ||
76 | To read a specific file in git-config format, use | |
77 | `git_config_from_file`. This takes the same callback and data parameters | |
78 | as `git_config`. | |
79 | ||
80 | Value Parsing Helpers | |
81 | --------------------- | |
82 | ||
83 | To aid in parsing string values, the config API provides callbacks with | |
84 | a number of helper functions, including: | |
85 | ||
86 | `git_config_int`:: | |
87 | Parse the string to an integer, including unit factors. Dies on error; | |
88 | otherwise, returns the parsed result. | |
89 | ||
90 | `git_config_ulong`:: | |
91 | Identical to `git_config_int`, but for unsigned longs. | |
92 | ||
93 | `git_config_bool`:: | |
94 | Parse a string into a boolean value, respecting keywords like "true" and | |
95 | "false". Integer values are converted into true/false values (when they | |
96 | are non-zero or zero, respectively). Other values cause a die(). If | |
97 | parsing is successful, the return value is the result. | |
98 | ||
99 | `git_config_bool_or_int`:: | |
100 | Same as `git_config_bool`, except that integers are returned as-is, and | |
101 | an `is_bool` flag is unset. | |
102 | ||
103 | `git_config_maybe_bool`:: | |
104 | Same as `git_config_bool`, except that it returns -1 on error rather | |
105 | than dying. | |
106 | ||
107 | `git_config_string`:: | |
108 | Allocates and copies the value string into the `dest` parameter; if no | |
109 | string is given, prints an error message and returns -1. | |
110 | ||
111 | `git_config_pathname`:: | |
112 | Similar to `git_config_string`, but expands `~` or `~user` into the | |
113 | user's home directory when found at the beginning of the path. | |
114 | ||
9b25a0b5 JK |
115 | Include Directives |
116 | ------------------ | |
117 | ||
118 | By default, the config parser does not respect include directives. | |
119 | However, a caller can use the special `git_config_include` wrapper | |
120 | callback to support them. To do so, you simply wrap your "real" callback | |
121 | function and data pointer in a `struct config_include_data`, and pass | |
122 | the wrapper to the regular config-reading functions. For example: | |
123 | ||
124 | ------------------------------------------- | |
125 | int read_file_with_include(const char *file, config_fn_t fn, void *data) | |
126 | { | |
127 | struct config_include_data inc = CONFIG_INCLUDE_INIT; | |
128 | inc.fn = fn; | |
129 | inc.data = data; | |
130 | return git_config_from_file(git_config_include, file, &inc); | |
131 | } | |
132 | ------------------------------------------- | |
133 | ||
134 | `git_config` respects includes automatically. The lower-level | |
135 | `git_config_from_file` does not. | |
136 | ||
9c3c22e2 JK |
137 | Writing Config Files |
138 | -------------------- | |
139 | ||
140 | TODO |