2 * Copyright (C) the libgit2 contributors. All rights reserved.
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.
7 #ifndef INCLUDE_git_submodule_h__
8 #define INCLUDE_git_submodule_h__
17 * @file git2/submodule.h
18 * @brief Git submodule management utilities
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.
26 * @defgroup git_submodule Git submodule management routines
33 * Return codes for submodule status.
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.
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
43 * depending on what state the repo is in. We consider all four places to
44 * build the combination of status flags.
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".
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
55 * The following values will be returned so long as ignore is not "ALL".
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
65 * The following can only be returned if ignore is "NONE" or "UNTRACKED".
67 * * WD_INDEX_MODIFIED - submodule workdir index is dirty
68 * * WD_WD_MODIFIED - submodule workdir has modified files
70 * Lastly, the following will only be returned for ignore "NONE".
72 * * WD_UNTRACKED - wd contains untracked files
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),
89 } git_submodule_status_t
;
91 #define GIT_SUBMODULE_STATUS__IN_FLAGS 0x000Fu
92 #define GIT_SUBMODULE_STATUS__INDEX_FLAGS 0x0070u
93 #define GIT_SUBMODULE_STATUS__WD_FLAGS 0x3F80u
95 #define GIT_SUBMODULE_STATUS_IS_UNMODIFIED(S) \
96 (((S) & ~GIT_SUBMODULE_STATUS__IN_FLAGS) == 0)
98 #define GIT_SUBMODULE_STATUS_IS_INDEX_UNMODIFIED(S) \
99 (((S) & GIT_SUBMODULE_STATUS__INDEX_FLAGS) == 0)
101 #define GIT_SUBMODULE_STATUS_IS_WD_UNMODIFIED(S) \
102 (((S) & (GIT_SUBMODULE_STATUS__WD_FLAGS & \
103 ~GIT_SUBMODULE_STATUS_WD_UNINITIALIZED)) == 0)
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)
111 * Function pointer to receive each submodule
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
118 typedef int GIT_CALLBACK(git_submodule_cb
)(
119 git_submodule
*sm
, const char *name
, void *payload
);
122 * Submodule update options structure
124 * Initialize with `GIT_SUBMODULE_UPDATE_OPTIONS_INIT`. Alternatively, you can
125 * use `git_submodule_update_options_init`.
128 typedef struct git_submodule_update_options
{
129 unsigned int version
;
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
138 git_checkout_options checkout_opts
;
141 * Options which control the fetch, including callbacks.
143 * The callbacks to use for reporting fetch progress, and for acquiring
144 * credentials in the event they are needed.
146 git_fetch_options fetch_opts
;
149 * Allow fetching from the submodule's default remote if the target
150 * commit isn't found. Enabled by default.
153 } git_submodule_update_options
;
155 #define GIT_SUBMODULE_UPDATE_OPTIONS_VERSION 1
156 #define GIT_SUBMODULE_UPDATE_OPTIONS_INIT \
157 { GIT_SUBMODULE_UPDATE_OPTIONS_VERSION, \
158 { GIT_CHECKOUT_OPTIONS_VERSION, GIT_CHECKOUT_SAFE }, \
159 GIT_FETCH_OPTIONS_INIT, 1 }
162 * Initialize git_submodule_update_options structure
164 * Initializes a `git_submodule_update_options` with default values. Equivalent to
165 * creating an instance with `GIT_SUBMODULE_UPDATE_OPTIONS_INIT`.
167 * @param opts The `git_submodule_update_options` struct to initialize.
168 * @param version The struct version; pass `GIT_SUBMODULE_UPDATE_OPTIONS_VERSION`.
169 * @return Zero on success; -1 on failure.
171 GIT_EXTERN(int) git_submodule_update_options_init(
172 git_submodule_update_options
*opts
, unsigned int version
);
175 * Update a submodule. This will clone a missing submodule and
176 * checkout the subrepository to the commit specified in the index of
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.
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
190 * `git_error_last` for a detailed error message).
192 GIT_EXTERN(int) git_submodule_update(git_submodule
*submodule
, int init
, git_submodule_update_options
*options
);
195 * Lookup submodule information by name or path.
197 * Given either the submodule name or path (they are usually the same), this
198 * returns a structure describing the submodule.
200 * There are two expected error scenarios:
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
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
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.
212 * You must call `git_submodule_free` when done with the submodule.
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
217 * @return 0 on success, GIT_ENOTFOUND if submodule does not exist,
218 * GIT_EEXISTS if a repository is found in working directory only,
219 * -1 on other errors.
221 GIT_EXTERN(int) git_submodule_lookup(
223 git_repository
*repo
,
227 * Create an in-memory copy of a submodule. The copy must be explicitly
228 * free'd or it will leak.
230 * @param out Pointer to store the copy of the submodule.
231 * @param source Original submodule to copy.
233 GIT_EXTERN(int) git_submodule_dup(git_submodule
**out
, git_submodule
*source
);
236 * Release a submodule
238 * @param submodule Submodule object
240 GIT_EXTERN(void) git_submodule_free(git_submodule
*submodule
);
243 * Iterate over all tracked submodules of a repository.
245 * See the note on `git_submodule` above. This iterates over the tracked
246 * submodules as described therein.
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.
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
260 GIT_EXTERN(int) git_submodule_foreach(
261 git_repository
*repo
,
262 git_submodule_cb callback
,
266 * Set up a new git submodule for checkout.
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.
274 * To fully emulate "git submodule add" call this function, then open the
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
277 * `git_submodule_add_finalize()` to wrap up adding the new submodule and
278 * .gitmodules to the index to be ready to commit.
280 * You must call `git_submodule_free` on the submodule object when done.
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
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.
291 GIT_EXTERN(int) git_submodule_add_setup(
293 git_repository
*repo
,
299 * Perform the clone step for a newly created submodule.
301 * This performs the necessary `git_clone` to setup a newly-created submodule.
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.
307 * @return 0 on success, -1 on other errors (see git_clone).
309 GIT_EXTERN(int) git_submodule_clone(
310 git_repository
**out
,
311 git_submodule
*submodule
,
312 const git_submodule_update_options
*opts
);
315 * Resolve the setup of a new git submodule.
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).
322 * @param submodule The submodule to finish adding.
324 GIT_EXTERN(int) git_submodule_add_finalize(git_submodule
*submodule
);
327 * Add current submodule HEAD commit to index of superproject.
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
334 * @return 0 on success, <0 on failure
336 GIT_EXTERN(int) git_submodule_add_to_index(
337 git_submodule
*submodule
,
341 * Get the containing repository for a submodule.
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
345 * original `git_submodule_lookup()` call, so if that repository has been
346 * freed, then this may be a dangling reference.
348 * @param submodule Pointer to submodule object
349 * @return Pointer to `git_repository`
351 GIT_EXTERN(git_repository
*) git_submodule_owner(git_submodule
*submodule
);
354 * Get the name of submodule.
356 * @param submodule Pointer to submodule object
357 * @return Pointer to the submodule name
359 GIT_EXTERN(const char *) git_submodule_name(git_submodule
*submodule
);
362 * Get the path to the submodule.
364 * The path is almost always the same as the submodule name, but the
365 * two are actually not required to match.
367 * @param submodule Pointer to submodule object
368 * @return Pointer to the submodule path
370 GIT_EXTERN(const char *) git_submodule_path(git_submodule
*submodule
);
373 * Get the URL for the submodule.
375 * @param submodule Pointer to submodule object
376 * @return Pointer to the submodule url
378 GIT_EXTERN(const char *) git_submodule_url(git_submodule
*submodule
);
381 * Resolve a submodule url relative to the given repository.
383 * @param out buffer to store the absolute submodule url in
384 * @param repo Pointer to repository object
385 * @param url Relative url
386 * @return 0 or an error code
388 GIT_EXTERN(int) git_submodule_resolve_url(git_buf
*out
, git_repository
*repo
, const char *url
);
391 * Get the branch for the submodule.
393 * @param submodule Pointer to submodule object
394 * @return Pointer to the submodule branch
396 GIT_EXTERN(const char *) git_submodule_branch(git_submodule
*submodule
);
399 * Set the branch for the submodule in the configuration
401 * After calling this, you may wish to call `git_submodule_sync()` to
402 * write the changes to the checked out submodule repository.
404 * @param repo the repository to affect
405 * @param name the name of the submodule to configure
406 * @param branch Branch that should be used for the submodule
407 * @return 0 on success, <0 on failure
409 GIT_EXTERN(int) git_submodule_set_branch(git_repository
*repo
, const char *name
, const char *branch
);
412 * Set the URL for the submodule in the configuration
415 * After calling this, you may wish to call `git_submodule_sync()` to
416 * write the changes to the checked out submodule repository.
418 * @param repo the repository to affect
419 * @param name the name of the submodule to configure
420 * @param url URL that should be used for the submodule
421 * @return 0 on success, <0 on failure
423 GIT_EXTERN(int) git_submodule_set_url(git_repository
*repo
, const char *name
, const char *url
);
426 * Get the OID for the submodule in the index.
428 * @param submodule Pointer to submodule object
429 * @return Pointer to git_oid or NULL if submodule is not in index.
431 GIT_EXTERN(const git_oid
*) git_submodule_index_id(git_submodule
*submodule
);
434 * Get the OID for the submodule in the current HEAD tree.
436 * @param submodule Pointer to submodule object
437 * @return Pointer to git_oid or NULL if submodule is not in the HEAD.
439 GIT_EXTERN(const git_oid
*) git_submodule_head_id(git_submodule
*submodule
);
442 * Get the OID for the submodule in the current working directory.
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
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.
449 * @param submodule Pointer to submodule object
450 * @return Pointer to git_oid or NULL if submodule is not checked out.
452 GIT_EXTERN(const git_oid
*) git_submodule_wd_id(git_submodule
*submodule
);
455 * Get the ignore rule that will be used for the submodule.
457 * These values control the behavior of `git_submodule_status()` for this
458 * submodule. There are four ignore values:
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
464 * working tree (i.e. call `git_status_foreach()` on the submodule) but
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.
473 * @param submodule The submodule to check
474 * @return The current git_submodule_ignore_t valyue what will be used for
477 GIT_EXTERN(git_submodule_ignore_t
) git_submodule_ignore(
478 git_submodule
*submodule
);
481 * Set the ignore rule for the submodule in the configuration
483 * This does not affect any currently-loaded instances.
485 * @param repo the repository to affect
486 * @param name the name of the submdule
487 * @param ignore The new value for the ignore rule
488 * @return 0 or an error code
490 GIT_EXTERN(int) git_submodule_set_ignore(
491 git_repository
*repo
,
493 git_submodule_ignore_t ignore
);
496 * Get the update rule that will be used for the submodule.
498 * This value controls the behavior of the `git submodule update` command.
499 * There are four useful values documented with `git_submodule_update_t`.
501 * @param submodule The submodule to check
502 * @return The current git_submodule_update_t value that will be used
503 * for this submodule.
505 GIT_EXTERN(git_submodule_update_t
) git_submodule_update_strategy(
506 git_submodule
*submodule
);
509 * Set the update rule for the submodule in the configuration
511 * This setting won't affect any existing instances.
513 * @param repo the repository to affect
514 * @param name the name of the submodule to configure
515 * @param update The new value to use
516 * @return 0 or an error code
518 GIT_EXTERN(int) git_submodule_set_update(
519 git_repository
*repo
,
521 git_submodule_update_t update
);
524 * Read the fetchRecurseSubmodules rule for a submodule.
526 * This accesses the submodule.<name>.fetchRecurseSubmodules value for
527 * the submodule that controls fetching behavior for the submodule.
529 * Note that at this time, libgit2 does not honor this setting and the
530 * fetch functionality current ignores submodules.
532 * @return 0 if fetchRecurseSubmodules is false, 1 if true
534 GIT_EXTERN(git_submodule_recurse_t
) git_submodule_fetch_recurse_submodules(
535 git_submodule
*submodule
);
538 * Set the fetchRecurseSubmodules rule for a submodule in the configuration
540 * This setting won't affect any existing instances.
542 * @param repo the repository to affect
543 * @param name the submodule to configure
544 * @param fetch_recurse_submodules Boolean value
545 * @return old value for fetchRecurseSubmodules
547 GIT_EXTERN(int) git_submodule_set_fetch_recurse_submodules(
548 git_repository
*repo
,
550 git_submodule_recurse_t fetch_recurse_submodules
);
553 * Copy submodule info into ".git/config" file.
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.
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.
565 GIT_EXTERN(int) git_submodule_init(git_submodule
*submodule
, int overwrite
);
568 * Set up the subrepository for a submodule in preparation for clone.
570 * This function can be called to init and set up a submodule
571 * repository from a submodule in preparation to clone it from
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.
580 GIT_EXTERN(int) git_submodule_repo_init(
581 git_repository
**out
,
582 const git_submodule
*sm
,
586 * Copy submodule remote info into submodule repo.
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.
593 GIT_EXTERN(int) git_submodule_sync(git_submodule
*submodule
);
596 * Open the repository for a submodule.
598 * This is a newly opened repository object. The caller is responsible for
599 * calling `git_repository_free()` on it when done. Multiple calls to this
600 * function will return distinct `git_repository` objects. This will only
601 * work if the submodule is checked out into the working directory.
603 * @param repo Pointer to the submodule repo which was opened
604 * @param submodule Submodule to be opened
605 * @return 0 on success, <0 if submodule repo could not be opened.
607 GIT_EXTERN(int) git_submodule_open(
608 git_repository
**repo
,
609 git_submodule
*submodule
);
612 * Reread submodule info from config, index, and HEAD.
614 * Call this to reread cached submodule information for this submodule if
615 * you have reason to believe that it has changed.
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
621 GIT_EXTERN(int) git_submodule_reload(git_submodule
*submodule
, int force
);
624 * Get the status for a submodule.
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
629 * on the `git_submodule_ignore_t` value for the submodule.
631 * @param status Combination of `GIT_SUBMODULE_STATUS` flags
632 * @param repo the repository in which to look
633 * @param name name of the submodule
634 * @param ignore the ignore rules to follow
635 * @return 0 on success, <0 on error
637 GIT_EXTERN(int) git_submodule_status(
638 unsigned int *status
,
639 git_repository
*repo
,
641 git_submodule_ignore_t ignore
);
644 * Get the locations of submodule information.
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.
653 * @param location_status Combination of first four `GIT_SUBMODULE_STATUS` flags
654 * @param submodule Submodule for which to get status
655 * @return 0 on success, <0 on error
657 GIT_EXTERN(int) git_submodule_location(
658 unsigned int *location_status
,
659 git_submodule
*submodule
);