]>
Commit | Line | Data |
---|---|---|
bfc9ca59 | 1 | /* |
359fc2d2 | 2 | * Copyright (C) the libgit2 contributors. All rights reserved. |
bfc9ca59 RB |
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_submodule_h__ | |
8 | #define INCLUDE_git_submodule_h__ | |
9 | ||
10 | #include "common.h" | |
11 | #include "types.h" | |
12 | #include "oid.h" | |
9d1f97df JM |
13 | #include "remote.h" |
14 | #include "checkout.h" | |
bfc9ca59 RB |
15 | |
16 | /** | |
17 | * @file git2/submodule.h | |
18 | * @brief Git submodule management utilities | |
aa13bf05 RB |
19 | * |
20 | * Submodule support in libgit2 builds a list of known submodules and keeps | |
21 | * it in the repository. The list is built from the .gitmodules file, the | |
22 | * .git/config file, the index, and the HEAD tree. Items in the working | |
23 | * directory that look like submodules (i.e. a git repo) but are not | |
24 | * mentioned in those places won't be tracked. | |
aa13bf05 | 25 | * |
f9775a37 RB |
26 | * @defgroup git_submodule Git submodule management routines |
27 | * @ingroup Git | |
28 | * @{ | |
aa13bf05 | 29 | */ |
f9775a37 | 30 | GIT_BEGIN_DECL |
bfc9ca59 | 31 | |
aa13bf05 RB |
32 | /** |
33 | * Return codes for submodule status. | |
34 | * | |
5f4a61ae RB |
35 | * A combination of these flags will be returned to describe the status of a |
36 | * submodule. Depending on the "ignore" property of the submodule, some of | |
37 | * the flags may never be returned because they indicate changes that are | |
38 | * supposed to be ignored. | |
aa13bf05 RB |
39 | * |
40 | * Submodule info is contained in 4 places: the HEAD tree, the index, config | |
41 | * files (both .git/config and .gitmodules), and the working directory. Any | |
42 | * or all of those places might be missing information about the submodule | |
5f4a61ae RB |
43 | * depending on what state the repo is in. We consider all four places to |
44 | * build the combination of status flags. | |
45 | * | |
46 | * There are four values that are not really status, but give basic info | |
47 | * about what sources of submodule data are available. These will be | |
48 | * returned even if ignore is set to "ALL". | |
49 | * | |
50 | * * IN_HEAD - superproject head contains submodule | |
51 | * * IN_INDEX - superproject index contains submodule | |
52 | * * IN_CONFIG - superproject gitmodules has submodule | |
53 | * * IN_WD - superproject workdir has submodule | |
54 | * | |
55 | * The following values will be returned so long as ignore is not "ALL". | |
56 | * | |
57 | * * INDEX_ADDED - in index, not in head | |
58 | * * INDEX_DELETED - in head, not in index | |
59 | * * INDEX_MODIFIED - index and head don't match | |
60 | * * WD_UNINITIALIZED - workdir contains empty directory | |
61 | * * WD_ADDED - in workdir, not index | |
62 | * * WD_DELETED - in index, not workdir | |
63 | * * WD_MODIFIED - index and workdir head don't match | |
64 | * | |
65 | * The following can only be returned if ignore is "NONE" or "UNTRACKED". | |
66 | * | |
67 | * * WD_INDEX_MODIFIED - submodule workdir index is dirty | |
68 | * * WD_WD_MODIFIED - submodule workdir has modified files | |
69 | * | |
70 | * Lastly, the following will only be returned for ignore "NONE". | |
71 | * | |
72 | * * WD_UNTRACKED - wd contains untracked files | |
aa13bf05 | 73 | */ |
5f4a61ae | 74 | typedef enum { |
e26b14c0 RB |
75 | GIT_SUBMODULE_STATUS_IN_HEAD = (1u << 0), |
76 | GIT_SUBMODULE_STATUS_IN_INDEX = (1u << 1), | |
77 | GIT_SUBMODULE_STATUS_IN_CONFIG = (1u << 2), | |
78 | GIT_SUBMODULE_STATUS_IN_WD = (1u << 3), | |
79 | GIT_SUBMODULE_STATUS_INDEX_ADDED = (1u << 4), | |
80 | GIT_SUBMODULE_STATUS_INDEX_DELETED = (1u << 5), | |
81 | GIT_SUBMODULE_STATUS_INDEX_MODIFIED = (1u << 6), | |
82 | GIT_SUBMODULE_STATUS_WD_UNINITIALIZED = (1u << 7), | |
83 | GIT_SUBMODULE_STATUS_WD_ADDED = (1u << 8), | |
84 | GIT_SUBMODULE_STATUS_WD_DELETED = (1u << 9), | |
85 | GIT_SUBMODULE_STATUS_WD_MODIFIED = (1u << 10), | |
86 | GIT_SUBMODULE_STATUS_WD_INDEX_MODIFIED = (1u << 11), | |
87 | GIT_SUBMODULE_STATUS_WD_WD_MODIFIED = (1u << 12), | |
88 | GIT_SUBMODULE_STATUS_WD_UNTRACKED = (1u << 13), | |
5f4a61ae RB |
89 | } git_submodule_status_t; |
90 | ||
1aad6137 RB |
91 | #define GIT_SUBMODULE_STATUS__IN_FLAGS 0x000Fu |
92 | #define GIT_SUBMODULE_STATUS__INDEX_FLAGS 0x0070u | |
93 | #define GIT_SUBMODULE_STATUS__WD_FLAGS 0x3F80u | |
ad26434b RB |
94 | |
95 | #define GIT_SUBMODULE_STATUS_IS_UNMODIFIED(S) \ | |
96 | (((S) & ~GIT_SUBMODULE_STATUS__IN_FLAGS) == 0) | |
97 | ||
98 | #define GIT_SUBMODULE_STATUS_IS_INDEX_UNMODIFIED(S) \ | |
99 | (((S) & GIT_SUBMODULE_STATUS__INDEX_FLAGS) == 0) | |
100 | ||
101 | #define GIT_SUBMODULE_STATUS_IS_WD_UNMODIFIED(S) \ | |
b554ca5d ET |
102 | (((S) & (GIT_SUBMODULE_STATUS__WD_FLAGS & \ |
103 | ~GIT_SUBMODULE_STATUS_WD_UNINITIALIZED)) == 0) | |
5d1308f2 RB |
104 | |
105 | #define GIT_SUBMODULE_STATUS_IS_WD_DIRTY(S) \ | |
106 | (((S) & (GIT_SUBMODULE_STATUS_WD_INDEX_MODIFIED | \ | |
107 | GIT_SUBMODULE_STATUS_WD_WD_MODIFIED | \ | |
108 | GIT_SUBMODULE_STATUS_WD_UNTRACKED)) != 0) | |
aa13bf05 | 109 | |
eda726cf | 110 | /** |
111 | * Function pointer to receive each submodule | |
112 | * | |
ab273821 | 113 | * @param sm git_submodule currently being visited |
114 | * @param name name of the submodule | |
115 | * @param payload value you passed to the foreach function as payload | |
116 | * @return 0 on success or error code | |
eda726cf | 117 | */ |
ac3d33df | 118 | typedef int GIT_CALLBACK(git_submodule_cb)( |
eda726cf | 119 | git_submodule *sm, const char *name, void *payload); |
120 | ||
9d1f97df JM |
121 | /** |
122 | * Submodule update options structure | |
123 | * | |
ac3d33df | 124 | * Initialize with `GIT_SUBMODULE_UPDATE_OPTIONS_INIT`. Alternatively, you can |
22a2d3d5 | 125 | * use `git_submodule_update_options_init`. |
9d1f97df | 126 | * |
9d1f97df JM |
127 | */ |
128 | typedef struct git_submodule_update_options { | |
129 | unsigned int version; | |
130 | ||
131 | /** | |
132 | * These options are passed to the checkout step. To disable | |
133 | * checkout, set the `checkout_strategy` to | |
134 | * `GIT_CHECKOUT_NONE`. Generally you will want the use | |
135 | * GIT_CHECKOUT_SAFE to update files in the working | |
ac3d33df | 136 | * directory. |
9d1f97df JM |
137 | */ |
138 | git_checkout_options checkout_opts; | |
139 | ||
140 | /** | |
8f0104ec CMN |
141 | * Options which control the fetch, including callbacks. |
142 | * | |
143 | * The callbacks to use for reporting fetch progress, and for acquiring | |
9d1f97df JM |
144 | * credentials in the event they are needed. |
145 | */ | |
8f0104ec | 146 | git_fetch_options fetch_opts; |
9d1f97df | 147 | |
de43efcf JH |
148 | /** |
149 | * Allow fetching from the submodule's default remote if the target | |
150 | * commit isn't found. Enabled by default. | |
151 | */ | |
152 | int allow_fetch; | |
9d1f97df JM |
153 | } git_submodule_update_options; |
154 | ||
155 | #define GIT_SUBMODULE_UPDATE_OPTIONS_VERSION 1 | |
c868981f | 156 | #define GIT_SUBMODULE_UPDATE_OPTIONS_INIT \ |
de43efcf | 157 | { GIT_SUBMODULE_UPDATE_OPTIONS_VERSION, \ |
96b82b11 | 158 | { GIT_CHECKOUT_OPTIONS_VERSION, GIT_CHECKOUT_SAFE }, \ |
3e22bb71 | 159 | GIT_FETCH_OPTIONS_INIT, 1 } |
c868981f DC |
160 | |
161 | /** | |
ac3d33df | 162 | * Initialize git_submodule_update_options structure |
c868981f | 163 | * |
ac3d33df JK |
164 | * Initializes a `git_submodule_update_options` with default values. Equivalent to |
165 | * creating an instance with `GIT_SUBMODULE_UPDATE_OPTIONS_INIT`. | |
166 | * | |
167 | * @param opts The `git_submodule_update_options` struct to initialize. | |
168 | * @param version The struct version; pass `GIT_SUBMODULE_UPDATE_OPTIONS_VERSION`. | |
c868981f DC |
169 | * @return Zero on success; -1 on failure. |
170 | */ | |
22a2d3d5 | 171 | GIT_EXTERN(int) git_submodule_update_options_init( |
c868981f | 172 | git_submodule_update_options *opts, unsigned int version); |
9d1f97df JM |
173 | |
174 | /** | |
175 | * Update a submodule. This will clone a missing submodule and | |
176 | * checkout the subrepository to the commit specified in the index of | |
de43efcf JH |
177 | * the containing repository. If the submodule repository doesn't contain |
178 | * the target commit (e.g. because fetchRecurseSubmodules isn't set), then | |
179 | * the submodule is fetched using the fetch options supplied in options. | |
9d1f97df JM |
180 | * |
181 | * @param submodule Submodule object | |
182 | * @param init If the submodule is not initialized, setting this flag to true | |
183 | * will initialize the submodule before updating. Otherwise, this will | |
184 | * return an error if attempting to update an uninitialzed repository. | |
185 | * but setting this to true forces them to be updated. | |
186 | * @param options configuration options for the update. If NULL, the | |
187 | * function works as though GIT_SUBMODULE_UPDATE_OPTIONS_INIT was passed. | |
188 | * @return 0 on success, any non-zero return value from a callback | |
189 | * function, or a negative value to indicate an error (use | |
ac3d33df | 190 | * `git_error_last` for a detailed error message). |
9d1f97df JM |
191 | */ |
192 | GIT_EXTERN(int) git_submodule_update(git_submodule *submodule, int init, git_submodule_update_options *options); | |
193 | ||
aa13bf05 RB |
194 | /** |
195 | * Lookup submodule information by name or path. | |
196 | * | |
197 | * Given either the submodule name or path (they are usually the same), this | |
198 | * returns a structure describing the submodule. | |
199 | * | |
200 | * There are two expected error scenarios: | |
bfc9ca59 | 201 | * |
aa13bf05 RB |
202 | * - The submodule is not mentioned in the HEAD, the index, and the config, |
203 | * but does "exist" in the working directory (i.e. there is a subdirectory | |
22df47cb RB |
204 | * that appears to be a Git repository). In this case, this function |
205 | * returns GIT_EEXISTS to indicate a sub-repository exists but not in a | |
aa13bf05 RB |
206 | * state where a git_submodule can be instantiated. |
207 | * - The submodule is not mentioned in the HEAD, index, or config and the | |
208 | * working directory doesn't contain a value git repo at that path. | |
209 | * There may or may not be anything else at that path, but nothing that | |
210 | * looks like a submodule. In this case, this returns GIT_ENOTFOUND. | |
bfc9ca59 | 211 | * |
a15c7802 | 212 | * You must call `git_submodule_free` when done with the submodule. |
bfc9ca59 | 213 | * |
a15c7802 RB |
214 | * @param out Output ptr to submodule; pass NULL to just get return code |
215 | * @param repo The parent repository | |
216 | * @param name The name of or path to the submodule; trailing slashes okay | |
aa13bf05 | 217 | * @return 0 on success, GIT_ENOTFOUND if submodule does not exist, |
22df47cb | 218 | * GIT_EEXISTS if a repository is found in working directory only, |
a15c7802 | 219 | * -1 on other errors. |
bfc9ca59 | 220 | */ |
aa13bf05 | 221 | GIT_EXTERN(int) git_submodule_lookup( |
a15c7802 | 222 | git_submodule **out, |
aa13bf05 RB |
223 | git_repository *repo, |
224 | const char *name); | |
bfc9ca59 | 225 | |
c25aa7cd PP |
226 | /** |
227 | * Create an in-memory copy of a submodule. The copy must be explicitly | |
228 | * free'd or it will leak. | |
229 | * | |
230 | * @param out Pointer to store the copy of the submodule. | |
231 | * @param source Original submodule to copy. | |
232 | */ | |
233 | GIT_EXTERN(int) git_submodule_dup(git_submodule **out, git_submodule *source); | |
234 | ||
a15c7802 RB |
235 | /** |
236 | * Release a submodule | |
237 | * | |
238 | * @param submodule Submodule object | |
239 | */ | |
240 | GIT_EXTERN(void) git_submodule_free(git_submodule *submodule); | |
241 | ||
bfc9ca59 | 242 | /** |
aa13bf05 RB |
243 | * Iterate over all tracked submodules of a repository. |
244 | * | |
245 | * See the note on `git_submodule` above. This iterates over the tracked | |
b874629b | 246 | * submodules as described therein. |
aa13bf05 RB |
247 | * |
248 | * If you are concerned about items in the working directory that look like | |
249 | * submodules but are not tracked, the diff API will generate a diff record | |
250 | * for workdir items that look like submodules but are not tracked, showing | |
251 | * them as added in the workdir. Also, the status API will treat the entire | |
252 | * subdirectory of a contained git repo as a single GIT_STATUS_WT_NEW item. | |
bfc9ca59 RB |
253 | * |
254 | * @param repo The repository | |
255 | * @param callback Function to be called with the name of each submodule. | |
256 | * Return a non-zero value to terminate the iteration. | |
257 | * @param payload Extra data to pass to callback | |
258 | * @return 0 on success, -1 on error, or non-zero return value of callback | |
259 | */ | |
260 | GIT_EXTERN(int) git_submodule_foreach( | |
261 | git_repository *repo, | |
eda726cf | 262 | git_submodule_cb callback, |
bfc9ca59 RB |
263 | void *payload); |
264 | ||
bfc9ca59 | 265 | /** |
aa13bf05 | 266 | * Set up a new git submodule for checkout. |
bfc9ca59 | 267 | * |
aa13bf05 RB |
268 | * This does "git submodule add" up to the fetch and checkout of the |
269 | * submodule contents. It preps a new submodule, creates an entry in | |
270 | * .gitmodules and creates an empty initialized repository either at the | |
271 | * given path in the working directory or in .git/modules with a gitlink | |
272 | * from the working directory to the new repo. | |
bfc9ca59 | 273 | * |
aa13bf05 | 274 | * To fully emulate "git submodule add" call this function, then open the |
22a2d3d5 UG |
275 | * submodule repo and perform the clone step as needed (if you don't need |
276 | * anything custom see `git_submodule_add_clone()`). Lastly, call | |
5f4a61ae | 277 | * `git_submodule_add_finalize()` to wrap up adding the new submodule and |
aa13bf05 RB |
278 | * .gitmodules to the index to be ready to commit. |
279 | * | |
a15c7802 RB |
280 | * You must call `git_submodule_free` on the submodule object when done. |
281 | * | |
282 | * @param out The newly created submodule ready to open for clone | |
283 | * @param repo The repository in which you want to create the submodule | |
284 | * @param url URL for the submodule's remote | |
aa13bf05 RB |
285 | * @param path Path at which the submodule should be created |
286 | * @param use_gitlink Should workdir contain a gitlink to the repo in | |
287 | * .git/modules vs. repo directly in workdir. | |
288 | * @return 0 on success, GIT_EEXISTS if submodule already exists, | |
289 | * -1 on other errors. | |
bfc9ca59 | 290 | */ |
aa13bf05 | 291 | GIT_EXTERN(int) git_submodule_add_setup( |
a15c7802 | 292 | git_submodule **out, |
bfc9ca59 | 293 | git_repository *repo, |
aa13bf05 RB |
294 | const char *url, |
295 | const char *path, | |
296 | int use_gitlink); | |
297 | ||
22a2d3d5 UG |
298 | /** |
299 | * Perform the clone step for a newly created submodule. | |
300 | * | |
301 | * This performs the necessary `git_clone` to setup a newly-created submodule. | |
302 | * | |
303 | * @param out The newly created repository object. Optional. | |
304 | * @param submodule The submodule currently waiting for its clone. | |
305 | * @param opts The options to use. | |
306 | * | |
307 | * @return 0 on success, -1 on other errors (see git_clone). | |
308 | */ | |
309 | GIT_EXTERN(int) git_submodule_clone( | |
310 | git_repository **out, | |
311 | git_submodule *submodule, | |
312 | const git_submodule_update_options *opts); | |
313 | ||
aa13bf05 RB |
314 | /** |
315 | * Resolve the setup of a new git submodule. | |
316 | * | |
317 | * This should be called on a submodule once you have called add setup | |
318 | * and done the clone of the submodule. This adds the .gitmodules file | |
319 | * and the newly cloned submodule to the index to be ready to be committed | |
320 | * (but doesn't actually do the commit). | |
5f4a61ae RB |
321 | * |
322 | * @param submodule The submodule to finish adding. | |
aa13bf05 RB |
323 | */ |
324 | GIT_EXTERN(int) git_submodule_add_finalize(git_submodule *submodule); | |
325 | ||
326 | /** | |
327 | * Add current submodule HEAD commit to index of superproject. | |
5f4a61ae RB |
328 | * |
329 | * @param submodule The submodule to add to the index | |
330 | * @param write_index Boolean if this should immediately write the index | |
331 | * file. If you pass this as false, you will have to get the | |
332 | * git_index and explicitly call `git_index_write()` on it to | |
333 | * save the change. | |
334 | * @return 0 on success, <0 on failure | |
aa13bf05 | 335 | */ |
5f4a61ae RB |
336 | GIT_EXTERN(int) git_submodule_add_to_index( |
337 | git_submodule *submodule, | |
338 | int write_index); | |
aa13bf05 | 339 | |
aa13bf05 RB |
340 | /** |
341 | * Get the containing repository for a submodule. | |
342 | * | |
343 | * This returns a pointer to the repository that contains the submodule. | |
344 | * This is a just a reference to the repository that was passed to the | |
5f4a61ae | 345 | * original `git_submodule_lookup()` call, so if that repository has been |
aa13bf05 RB |
346 | * freed, then this may be a dangling reference. |
347 | * | |
348 | * @param submodule Pointer to submodule object | |
349 | * @return Pointer to `git_repository` | |
350 | */ | |
351 | GIT_EXTERN(git_repository *) git_submodule_owner(git_submodule *submodule); | |
352 | ||
353 | /** | |
354 | * Get the name of submodule. | |
355 | * | |
356 | * @param submodule Pointer to submodule object | |
357 | * @return Pointer to the submodule name | |
358 | */ | |
359 | GIT_EXTERN(const char *) git_submodule_name(git_submodule *submodule); | |
360 | ||
361 | /** | |
362 | * Get the path to the submodule. | |
363 | * | |
364 | * The path is almost always the same as the submodule name, but the | |
365 | * two are actually not required to match. | |
366 | * | |
367 | * @param submodule Pointer to submodule object | |
368 | * @return Pointer to the submodule path | |
369 | */ | |
370 | GIT_EXTERN(const char *) git_submodule_path(git_submodule *submodule); | |
371 | ||
372 | /** | |
373 | * Get the URL for the submodule. | |
374 | * | |
375 | * @param submodule Pointer to submodule object | |
376 | * @return Pointer to the submodule url | |
377 | */ | |
378 | GIT_EXTERN(const char *) git_submodule_url(git_submodule *submodule); | |
379 | ||
52fba18f JM |
380 | /** |
381 | * Resolve a submodule url relative to the given repository. | |
382 | * | |
383 | * @param out buffer to store the absolute submodule url in | |
31b0cb51 | 384 | * @param repo Pointer to repository object |
52fba18f JM |
385 | * @param url Relative url |
386 | * @return 0 or an error code | |
387 | */ | |
388 | GIT_EXTERN(int) git_submodule_resolve_url(git_buf *out, git_repository *repo, const char *url); | |
389 | ||
10311979 RK |
390 | /** |
391 | * Get the branch for the submodule. | |
392 | * | |
393 | * @param submodule Pointer to submodule object | |
394 | * @return Pointer to the submodule branch | |
395 | */ | |
396 | GIT_EXTERN(const char *) git_submodule_branch(git_submodule *submodule); | |
397 | ||
129788a6 | 398 | /** |
486ba4cd | 399 | * Set the branch for the submodule in the configuration |
129788a6 | 400 | * |
486ba4cd | 401 | * After calling this, you may wish to call `git_submodule_sync()` to |
129788a6 PS |
402 | * write the changes to the checked out submodule repository. |
403 | * | |
486ba4cd CMN |
404 | * @param repo the repository to affect |
405 | * @param name the name of the submodule to configure | |
129788a6 PS |
406 | * @param branch Branch that should be used for the submodule |
407 | * @return 0 on success, <0 on failure | |
408 | */ | |
486ba4cd | 409 | GIT_EXTERN(int) git_submodule_set_branch(git_repository *repo, const char *name, const char *branch); |
129788a6 | 410 | |
aa13bf05 | 411 | /** |
d6073b30 | 412 | * Set the URL for the submodule in the configuration |
aa13bf05 | 413 | * |
aa13bf05 | 414 | * |
d6073b30 | 415 | * After calling this, you may wish to call `git_submodule_sync()` to |
aa13bf05 RB |
416 | * write the changes to the checked out submodule repository. |
417 | * | |
d6073b30 CMN |
418 | * @param repo the repository to affect |
419 | * @param name the name of the submodule to configure | |
aa13bf05 RB |
420 | * @param url URL that should be used for the submodule |
421 | * @return 0 on success, <0 on failure | |
422 | */ | |
d6073b30 | 423 | GIT_EXTERN(int) git_submodule_set_url(git_repository *repo, const char *name, const char *url); |
aa13bf05 RB |
424 | |
425 | /** | |
426 | * Get the OID for the submodule in the index. | |
427 | * | |
428 | * @param submodule Pointer to submodule object | |
429 | * @return Pointer to git_oid or NULL if submodule is not in index. | |
430 | */ | |
9cd42358 | 431 | GIT_EXTERN(const git_oid *) git_submodule_index_id(git_submodule *submodule); |
aa13bf05 RB |
432 | |
433 | /** | |
434 | * Get the OID for the submodule in the current HEAD tree. | |
435 | * | |
436 | * @param submodule Pointer to submodule object | |
437 | * @return Pointer to git_oid or NULL if submodule is not in the HEAD. | |
438 | */ | |
9cd42358 | 439 | GIT_EXTERN(const git_oid *) git_submodule_head_id(git_submodule *submodule); |
aa13bf05 RB |
440 | |
441 | /** | |
442 | * Get the OID for the submodule in the current working directory. | |
443 | * | |
444 | * This returns the OID that corresponds to looking up 'HEAD' in the checked | |
445 | * out submodule. If there are pending changes in the index or anything | |
5f4a61ae RB |
446 | * else, this won't notice that. You should call `git_submodule_status()` |
447 | * for a more complete picture about the state of the working directory. | |
aa13bf05 RB |
448 | * |
449 | * @param submodule Pointer to submodule object | |
450 | * @return Pointer to git_oid or NULL if submodule is not checked out. | |
451 | */ | |
9cd42358 | 452 | GIT_EXTERN(const git_oid *) git_submodule_wd_id(git_submodule *submodule); |
aa13bf05 RB |
453 | |
454 | /** | |
9b7d02ff | 455 | * Get the ignore rule that will be used for the submodule. |
aa13bf05 | 456 | * |
9b7d02ff RB |
457 | * These values control the behavior of `git_submodule_status()` for this |
458 | * submodule. There are four ignore values: | |
aa13bf05 RB |
459 | * |
460 | * - **GIT_SUBMODULE_IGNORE_NONE** will consider any change to the contents | |
461 | * of the submodule from a clean checkout to be dirty, including the | |
462 | * addition of untracked files. This is the default if unspecified. | |
463 | * - **GIT_SUBMODULE_IGNORE_UNTRACKED** examines the contents of the | |
5f4a61ae | 464 | * working tree (i.e. call `git_status_foreach()` on the submodule) but |
aa13bf05 RB |
465 | * UNTRACKED files will not count as making the submodule dirty. |
466 | * - **GIT_SUBMODULE_IGNORE_DIRTY** means to only check if the HEAD of the | |
467 | * submodule has moved for status. This is fast since it does not need to | |
468 | * scan the working tree of the submodule at all. | |
469 | * - **GIT_SUBMODULE_IGNORE_ALL** means not to open the submodule repo. | |
470 | * The working directory will be consider clean so long as there is a | |
471 | * checked out version present. | |
9b7d02ff | 472 | * |
9b7d02ff RB |
473 | * @param submodule The submodule to check |
474 | * @return The current git_submodule_ignore_t valyue what will be used for | |
475 | * this submodule. | |
aa13bf05 RB |
476 | */ |
477 | GIT_EXTERN(git_submodule_ignore_t) git_submodule_ignore( | |
478 | git_submodule *submodule); | |
479 | ||
480 | /** | |
5a9fc6c8 | 481 | * Set the ignore rule for the submodule in the configuration |
aa13bf05 | 482 | * |
5a9fc6c8 | 483 | * This does not affect any currently-loaded instances. |
aa13bf05 | 484 | * |
5a9fc6c8 CMN |
485 | * @param repo the repository to affect |
486 | * @param name the name of the submdule | |
9b7d02ff | 487 | * @param ignore The new value for the ignore rule |
5a9fc6c8 | 488 | * @return 0 or an error code |
aa13bf05 | 489 | */ |
5a9fc6c8 CMN |
490 | GIT_EXTERN(int) git_submodule_set_ignore( |
491 | git_repository *repo, | |
492 | const char *name, | |
aa13bf05 RB |
493 | git_submodule_ignore_t ignore); |
494 | ||
495 | /** | |
9b7d02ff RB |
496 | * Get the update rule that will be used for the submodule. |
497 | * | |
498 | * This value controls the behavior of the `git submodule update` command. | |
783672fa | 499 | * There are four useful values documented with `git_submodule_update_t`. |
9b7d02ff RB |
500 | * |
501 | * @param submodule The submodule to check | |
502 | * @return The current git_submodule_update_t value that will be used | |
503 | * for this submodule. | |
aa13bf05 | 504 | */ |
9d1f97df | 505 | GIT_EXTERN(git_submodule_update_t) git_submodule_update_strategy( |
aa13bf05 RB |
506 | git_submodule *submodule); |
507 | ||
508 | /** | |
e8a39f8e | 509 | * Set the update rule for the submodule in the configuration |
aa13bf05 | 510 | * |
e8a39f8e | 511 | * This setting won't affect any existing instances. |
aa13bf05 | 512 | * |
e8a39f8e CMN |
513 | * @param repo the repository to affect |
514 | * @param name the name of the submodule to configure | |
9b7d02ff | 515 | * @param update The new value to use |
e8a39f8e | 516 | * @return 0 or an error code |
aa13bf05 | 517 | */ |
e8a39f8e CMN |
518 | GIT_EXTERN(int) git_submodule_set_update( |
519 | git_repository *repo, | |
520 | const char *name, | |
aa13bf05 RB |
521 | git_submodule_update_t update); |
522 | ||
17b06f4d RB |
523 | /** |
524 | * Read the fetchRecurseSubmodules rule for a submodule. | |
525 | * | |
526 | * This accesses the submodule.<name>.fetchRecurseSubmodules value for | |
527 | * the submodule that controls fetching behavior for the submodule. | |
528 | * | |
529 | * Note that at this time, libgit2 does not honor this setting and the | |
530 | * fetch functionality current ignores submodules. | |
531 | * | |
532 | * @return 0 if fetchRecurseSubmodules is false, 1 if true | |
533 | */ | |
fccadba2 | 534 | GIT_EXTERN(git_submodule_recurse_t) git_submodule_fetch_recurse_submodules( |
17b06f4d RB |
535 | git_submodule *submodule); |
536 | ||
537 | /** | |
4e636423 | 538 | * Set the fetchRecurseSubmodules rule for a submodule in the configuration |
17b06f4d | 539 | * |
4e636423 | 540 | * This setting won't affect any existing instances. |
17b06f4d | 541 | * |
4e636423 CMN |
542 | * @param repo the repository to affect |
543 | * @param name the submodule to configure | |
17b06f4d RB |
544 | * @param fetch_recurse_submodules Boolean value |
545 | * @return old value for fetchRecurseSubmodules | |
546 | */ | |
4e636423 CMN |
547 | GIT_EXTERN(int) git_submodule_set_fetch_recurse_submodules( |
548 | git_repository *repo, | |
549 | const char *name, | |
fccadba2 | 550 | git_submodule_recurse_t fetch_recurse_submodules); |
17b06f4d | 551 | |
aa13bf05 RB |
552 | /** |
553 | * Copy submodule info into ".git/config" file. | |
554 | * | |
555 | * Just like "git submodule init", this copies information about the | |
556 | * submodule into ".git/config". You can use the accessor functions | |
557 | * above to alter the in-memory git_submodule object and control what | |
558 | * is written to the config, overriding what is in .gitmodules. | |
559 | * | |
560 | * @param submodule The submodule to write into the superproject config | |
561 | * @param overwrite By default, existing entries will not be overwritten, | |
562 | * but setting this to true forces them to be updated. | |
563 | * @return 0 on success, <0 on failure. | |
564 | */ | |
565 | GIT_EXTERN(int) git_submodule_init(git_submodule *submodule, int overwrite); | |
566 | ||
bc737620 JM |
567 | /** |
568 | * Set up the subrepository for a submodule in preparation for clone. | |
569 | * | |
570 | * This function can be called to init and set up a submodule | |
571 | * repository from a submodule in preparation to clone it from | |
572 | * its remote. | |
573 | * | |
574 | * @param out Output pointer to the created git repository. | |
575 | * @param sm The submodule to create a new subrepository from. | |
576 | * @param use_gitlink Should the workdir contain a gitlink to | |
577 | * the repo in .git/modules vs. repo directly in workdir. | |
578 | * @return 0 on success, <0 on failure. | |
579 | */ | |
580 | GIT_EXTERN(int) git_submodule_repo_init( | |
581 | git_repository **out, | |
582 | const git_submodule *sm, | |
583 | int use_gitlink); | |
584 | ||
aa13bf05 RB |
585 | /** |
586 | * Copy submodule remote info into submodule repo. | |
587 | * | |
588 | * This copies the information about the submodules URL into the checked out | |
589 | * submodule config, acting like "git submodule sync". This is useful if | |
590 | * you have altered the URL for the submodule (or it has been altered by a | |
591 | * fetch of upstream changes) and you need to update your local repo. | |
592 | */ | |
593 | GIT_EXTERN(int) git_submodule_sync(git_submodule *submodule); | |
594 | ||
595 | /** | |
596 | * Open the repository for a submodule. | |
597 | * | |
598 | * This is a newly opened repository object. The caller is responsible for | |
5f4a61ae | 599 | * calling `git_repository_free()` on it when done. Multiple calls to this |
aa13bf05 RB |
600 | * function will return distinct `git_repository` objects. This will only |
601 | * work if the submodule is checked out into the working directory. | |
602 | * | |
e1967164 | 603 | * @param repo Pointer to the submodule repo which was opened |
aa13bf05 RB |
604 | * @param submodule Submodule to be opened |
605 | * @return 0 on success, <0 if submodule repo could not be opened. | |
606 | */ | |
607 | GIT_EXTERN(int) git_submodule_open( | |
608 | git_repository **repo, | |
609 | git_submodule *submodule); | |
610 | ||
611 | /** | |
612 | * Reread submodule info from config, index, and HEAD. | |
613 | * | |
614 | * Call this to reread cached submodule information for this submodule if | |
615 | * you have reason to believe that it has changed. | |
a15c7802 RB |
616 | * |
617 | * @param submodule The submodule to reload | |
618 | * @param force Force reload even if the data doesn't seem out of date | |
619 | * @return 0 on success, <0 on error | |
aa13bf05 | 620 | */ |
a15c7802 | 621 | GIT_EXTERN(int) git_submodule_reload(git_submodule *submodule, int force); |
aa13bf05 | 622 | |
aa13bf05 RB |
623 | /** |
624 | * Get the status for a submodule. | |
625 | * | |
626 | * This looks at a submodule and tries to determine the status. It | |
627 | * will return a combination of the `GIT_SUBMODULE_STATUS` values above. | |
628 | * How deeply it examines the working directory to do this will depend | |
64bbd47a | 629 | * on the `git_submodule_ignore_t` value for the submodule. |
aa13bf05 | 630 | * |
5f4a61ae | 631 | * @param status Combination of `GIT_SUBMODULE_STATUS` flags |
64bbd47a CMN |
632 | * @param repo the repository in which to look |
633 | * @param name name of the submodule | |
c6f489c9 | 634 | * @param ignore the ignore rules to follow |
aa13bf05 RB |
635 | * @return 0 on success, <0 on error |
636 | */ | |
637 | GIT_EXTERN(int) git_submodule_status( | |
638 | unsigned int *status, | |
64bbd47a | 639 | git_repository *repo, |
c6f489c9 CMN |
640 | const char *name, |
641 | git_submodule_ignore_t ignore); | |
bfc9ca59 | 642 | |
a9a73007 RB |
643 | /** |
644 | * Get the locations of submodule information. | |
645 | * | |
646 | * This is a bit like a very lightweight version of `git_submodule_status`. | |
647 | * It just returns a made of the first four submodule status values (i.e. | |
648 | * the ones like GIT_SUBMODULE_STATUS_IN_HEAD, etc) that tell you where the | |
649 | * submodule data comes from (i.e. the HEAD commit, gitmodules file, etc.). | |
650 | * This can be useful if you want to know if the submodule is present in the | |
651 | * working directory at this point in time, etc. | |
652 | * | |
e1967164 | 653 | * @param location_status Combination of first four `GIT_SUBMODULE_STATUS` flags |
a9a73007 RB |
654 | * @param submodule Submodule for which to get status |
655 | * @return 0 on success, <0 on error | |
656 | */ | |
657 | GIT_EXTERN(int) git_submodule_location( | |
658 | unsigned int *location_status, | |
659 | git_submodule *submodule); | |
660 | ||
bfc9ca59 RB |
661 | /** @} */ |
662 | GIT_END_DECL | |
663 | #endif |