]>
Commit | Line | Data |
---|---|---|
5d4cd003 | 1 | /* |
5e0de328 | 2 | * Copyright (C) 2009-2012 the libgit2 contributors |
5d4cd003 | 3 | * |
bb742ede VM |
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. | |
5d4cd003 CMN |
6 | */ |
7 | #ifndef INCLUDE_git_config_h__ | |
8 | #define INCLUDE_git_config_h__ | |
9 | ||
10 | #include "common.h" | |
9a3c5e55 | 11 | #include "types.h" |
5d4cd003 CMN |
12 | |
13 | /** | |
9a3c5e55 | 14 | * @file git2/config.h |
5d4cd003 | 15 | * @brief Git config management routines |
9a3c5e55 | 16 | * @defgroup git_config Git config management routines |
5d4cd003 CMN |
17 | * @ingroup Git |
18 | * @{ | |
19 | */ | |
20 | GIT_BEGIN_DECL | |
21 | ||
b0b527e0 VM |
22 | /** |
23 | * Generic backend that implements the interface to | |
24 | * access a configuration file | |
25 | */ | |
26 | struct git_config_file { | |
27 | struct git_config *cfg; | |
28 | ||
29 | /* Open means open the file/database and parse if necessary */ | |
30 | int (*open)(struct git_config_file *); | |
31 | int (*get)(struct git_config_file *, const char *key, const char **value); | |
32 | int (*set)(struct git_config_file *, const char *key, const char *value); | |
9dd4c3e8 | 33 | int (*del)(struct git_config_file *, const char *key); |
cfef5fb7 | 34 | int (*foreach)(struct git_config_file *, int (*fn)(const char *, const char *, void *), void *data); |
b0b527e0 VM |
35 | void (*free)(struct git_config_file *); |
36 | }; | |
37 | ||
19cb6857 VM |
38 | /** |
39 | * Locate the path to the global configuration file | |
40 | * | |
41 | * The user or global configuration file is usually | |
42 | * located in `$HOME/.gitconfig`. | |
43 | * | |
44 | * This method will try to guess the full path to that | |
45 | * file, if the file exists. The returned path | |
46 | * may be used on any `git_config` call to load the | |
47 | * global configuration file. | |
48 | * | |
bfd5e3e2 | 49 | * @param global_config_path Buffer of GIT_PATH_MAX length to store the path |
19cb6857 VM |
50 | * @return GIT_SUCCESS if a global configuration file has been |
51 | * found. Its path will be stored in `buffer`. | |
52 | */ | |
53 | GIT_EXTERN(int) git_config_find_global(char *global_config_path); | |
54 | ||
4c562347 CMN |
55 | /** |
56 | * Locate the path to the system configuration file | |
57 | * | |
58 | * If /etc/gitconfig doesn't exist, it will look for | |
59 | * %PROGRAMFILES%\Git\etc\gitconfig. | |
60 | ||
61 | * @param system_config_path Buffer of GIT_PATH_MAX length to store the path | |
62 | * @return GIT_SUCCESS if a system configuration file has been | |
63 | * found. Its path will be stored in `buffer`. | |
64 | */ | |
65 | GIT_EXTERN(int) git_config_find_system(char *system_config_path); | |
66 | ||
19cb6857 VM |
67 | /** |
68 | * Open the global configuration file | |
69 | * | |
70 | * Utility wrapper that calls `git_config_find_global` | |
71 | * and opens the located file, if it exists. | |
72 | * | |
73 | * @param out Pointer to store the config instance | |
d9111722 | 74 | * @return GIT_SUCCESS or an error code |
19cb6857 VM |
75 | */ |
76 | GIT_EXTERN(int) git_config_open_global(git_config **out); | |
77 | ||
b0b527e0 VM |
78 | /** |
79 | * Create a configuration file backend for ondisk files | |
80 | * | |
81 | * These are the normal `.gitconfig` files that Core Git | |
a2a305fc CMN |
82 | * processes. Note that you first have to add this file to a |
83 | * configuration object before you can query it for configuration | |
84 | * variables. | |
b0b527e0 VM |
85 | * |
86 | * @param out the new backend | |
19cb6857 | 87 | * @param path where the config file is located |
b0b527e0 VM |
88 | */ |
89 | GIT_EXTERN(int) git_config_file__ondisk(struct git_config_file **out, const char *path); | |
90 | ||
c0335005 | 91 | /** |
a2a305fc CMN |
92 | * Allocate a new configuration object |
93 | * | |
94 | * This object is empty, so you have to add a file to it before you | |
95 | * can do anything with it. | |
96 | * | |
97 | * @param out pointer to the new configuration | |
d9111722 | 98 | * @return GIT_SUCCESS or an error code |
c0335005 CMN |
99 | */ |
100 | GIT_EXTERN(int) git_config_new(git_config **out); | |
101 | ||
5d4cd003 | 102 | /** |
07ff8817 | 103 | * Add a generic config file instance to an existing config |
5d4cd003 | 104 | * |
07ff8817 VM |
105 | * Note that the configuration object will free the file |
106 | * automatically. | |
a2a305fc | 107 | * |
07ff8817 VM |
108 | * Further queries on this config object will access each |
109 | * of the config file instances in order (instances with | |
110 | * a higher priority will be accessed first). | |
32234541 | 111 | * |
07ff8817 VM |
112 | * @param cfg the configuration to add the file to |
113 | * @param file the configuration file (backend) to add | |
114 | * @param priority the priority the backend should have | |
d9111722 | 115 | * @return GIT_SUCCESS or an error code |
32234541 | 116 | */ |
07ff8817 | 117 | GIT_EXTERN(int) git_config_add_file(git_config *cfg, git_config_file *file, int priority); |
32234541 | 118 | |
c0335005 | 119 | /** |
07ff8817 VM |
120 | * Add an on-disk config file instance to an existing config |
121 | * | |
122 | * The on-disk file pointed at by `path` will be opened and | |
123 | * parsed; it's expected to be a native Git config file following | |
124 | * the default Git config syntax (see man git-config). | |
c0335005 | 125 | * |
a2a305fc CMN |
126 | * Note that the configuration object will free the file |
127 | * automatically. | |
f44cbec4 | 128 | * |
07ff8817 VM |
129 | * Further queries on this config object will access each |
130 | * of the config file instances in order (instances with | |
131 | * a higher priority will be accessed first). | |
132 | * | |
ce78f39e | 133 | * @param cfg the configuration to add the file to |
bfd5e3e2 | 134 | * @param path path to the configuration file (backend) to add |
f44cbec4 | 135 | * @param priority the priority the backend should have |
d9111722 | 136 | * @return GIT_SUCCESS or an error code |
c0335005 | 137 | */ |
07ff8817 VM |
138 | GIT_EXTERN(int) git_config_add_file_ondisk(git_config *cfg, const char *path, int priority); |
139 | ||
140 | ||
141 | /** | |
142 | * Create a new config instance containing a single on-disk file | |
143 | * | |
144 | * This method is a simple utility wrapper for the following sequence | |
145 | * of calls: | |
146 | * - git_config_new | |
147 | * - git_config_add_file_ondisk | |
148 | * | |
149 | * @param cfg The configuration instance to create | |
150 | * @param path Path to the on-disk file to open | |
d9111722 | 151 | * @return GIT_SUCCESS or an error code |
07ff8817 VM |
152 | */ |
153 | GIT_EXTERN(int) git_config_open_ondisk(git_config **cfg, const char *path); | |
5d4cd003 CMN |
154 | |
155 | /** | |
a2a305fc | 156 | * Free the configuration and its associated memory and files |
9a3c5e55 CMN |
157 | * |
158 | * @param cfg the configuration to free | |
5d4cd003 CMN |
159 | */ |
160 | GIT_EXTERN(void) git_config_free(git_config *cfg); | |
161 | ||
9a3c5e55 CMN |
162 | /** |
163 | * Get the value of an integer config variable. | |
164 | * | |
165 | * @param cfg where to look for the variable | |
166 | * @param name the variable's name | |
167 | * @param out pointer to the variable where the value should be stored | |
d9111722 | 168 | * @return GIT_SUCCESS or an error code |
9a3c5e55 | 169 | */ |
fafd4710 | 170 | GIT_EXTERN(int) git_config_get_int32(git_config *cfg, const char *name, int32_t *out); |
9a3c5e55 | 171 | |
e69ac243 CMN |
172 | /** |
173 | * Get the value of a long integer config variable. | |
174 | * | |
175 | * @param cfg where to look for the variable | |
176 | * @param name the variable's name | |
177 | * @param out pointer to the variable where the value should be stored | |
d9111722 | 178 | * @return GIT_SUCCESS or an error code |
e69ac243 | 179 | */ |
fafd4710 | 180 | GIT_EXTERN(int) git_config_get_int64(git_config *cfg, const char *name, int64_t *out); |
e69ac243 | 181 | |
9a3c5e55 CMN |
182 | /** |
183 | * Get the value of a boolean config variable. | |
184 | * | |
2974aa94 CMN |
185 | * This function uses the usual C convention of 0 being false and |
186 | * anything else true. | |
187 | * | |
9a3c5e55 CMN |
188 | * @param cfg where to look for the variable |
189 | * @param name the variable's name | |
190 | * @param out pointer to the variable where the value should be stored | |
d9111722 | 191 | * @return GIT_SUCCESS or an error code |
9a3c5e55 | 192 | */ |
2974aa94 | 193 | GIT_EXTERN(int) git_config_get_bool(git_config *cfg, const char *name, int *out); |
9a3c5e55 CMN |
194 | |
195 | /** | |
196 | * Get the value of a string config variable. | |
197 | * | |
198 | * The string is owned by the variable and should not be freed by the | |
199 | * user. | |
200 | * | |
201 | * @param cfg where to look for the variable | |
202 | * @param name the variable's name | |
203 | * @param out pointer to the variable's value | |
d9111722 | 204 | * @return GIT_SUCCESS or an error code |
9a3c5e55 CMN |
205 | */ |
206 | GIT_EXTERN(int) git_config_get_string(git_config *cfg, const char *name, const char **out); | |
9a3c5e55 CMN |
207 | |
208 | /** | |
209 | * Set the value of an integer config variable. | |
210 | * | |
211 | * @param cfg where to look for the variable | |
212 | * @param name the variable's name | |
d144c569 | 213 | * @param value Integer value for the variable |
d9111722 | 214 | * @return GIT_SUCCESS or an error code |
9a3c5e55 | 215 | */ |
fafd4710 | 216 | GIT_EXTERN(int) git_config_set_int32(git_config *cfg, const char *name, int32_t value); |
9a3c5e55 | 217 | |
e69ac243 CMN |
218 | /** |
219 | * Set the value of a long integer config variable. | |
220 | * | |
221 | * @param cfg where to look for the variable | |
222 | * @param name the variable's name | |
d144c569 | 223 | * @param value Long integer value for the variable |
d9111722 | 224 | * @return GIT_SUCCESS or an error code |
e69ac243 | 225 | */ |
fafd4710 | 226 | GIT_EXTERN(int) git_config_set_int64(git_config *cfg, const char *name, int64_t value); |
e69ac243 | 227 | |
9a3c5e55 CMN |
228 | /** |
229 | * Set the value of a boolean config variable. | |
230 | * | |
231 | * @param cfg where to look for the variable | |
232 | * @param name the variable's name | |
233 | * @param value the value to store | |
d9111722 | 234 | * @return GIT_SUCCESS or an error code |
9a3c5e55 | 235 | */ |
2974aa94 | 236 | GIT_EXTERN(int) git_config_set_bool(git_config *cfg, const char *name, int value); |
9a3c5e55 CMN |
237 | |
238 | /** | |
239 | * Set the value of a string config variable. | |
240 | * | |
241 | * A copy of the string is made and the user is free to use it | |
242 | * afterwards. | |
243 | * | |
244 | * @param cfg where to look for the variable | |
245 | * @param name the variable's name | |
246 | * @param value the string to store. | |
d9111722 | 247 | * @return GIT_SUCCESS or an error code |
9a3c5e55 CMN |
248 | */ |
249 | GIT_EXTERN(int) git_config_set_string(git_config *cfg, const char *name, const char *value); | |
250 | ||
251 | /** | |
2601fcfc CMN |
252 | * Delete a config variable |
253 | * | |
254 | * @param cfg the configuration | |
255 | * @param name the variable to delete | |
256 | */ | |
b08683ff | 257 | GIT_EXTERN(int) git_config_delete(git_config *cfg, const char *name); |
2601fcfc CMN |
258 | |
259 | /** | |
260 | * Perform an operation on each config variable. | |
9a3c5e55 | 261 | * |
cfef5fb7 VM |
262 | * The callback receives the normalized name and value of each variable |
263 | * in the config backend, and the data pointer passed to this function. | |
264 | * As soon as one of the callback functions returns something other than 0, | |
265 | * this function returns that value. | |
9a3c5e55 CMN |
266 | * |
267 | * @param cfg where to get the variables from | |
268 | * @param callback the function to call on each variable | |
e0fc39da | 269 | * @param payload the data to pass to the callback |
9a3c5e55 CMN |
270 | * @return GIT_SUCCESS or the return value of the callback which didn't return 0 |
271 | */ | |
cfef5fb7 VM |
272 | GIT_EXTERN(int) git_config_foreach( |
273 | git_config *cfg, | |
274 | int (*callback)(const char *var_name, const char *value, void *payload), | |
275 | void *payload); | |
9a3c5e55 | 276 | |
5d4cd003 CMN |
277 | /** @} */ |
278 | GIT_END_DECL | |
279 | #endif |