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_submodule_h__
8 #define INCLUDE_submodule_h__
10 #include "git2/submodule.h"
11 #include "git2/repository.h"
16 * Submodule information can be in four places: the index, the config files
17 * (both .git/config and .gitmodules), the HEAD tree, and the working
21 * - submodule is found by path
22 * - may be missing, present, or of the wrong type
23 * - will have an oid if present
26 * - submodule is found by path
27 * - may be missing, present, or of the wrong type
28 * - will have an oid if present
30 * In the config files:
31 * - submodule is found by submodule "name" which is usually the path
32 * - may be missing or present
33 * - will have a name, path, url, and other properties
35 * In the working directory:
36 * - submodule is found by path
37 * - may be missing, an empty directory, a checked out directory,
38 * or of the wrong type
39 * - if checked out, will have a HEAD oid
40 * - if checked out, will have git history that can be used to compare oids
41 * - if checked out, may have modified files and/or untracked files
45 * Description of submodule
47 * This record describes a submodule found in a repository. There should be
48 * an entry for every submodule found in the HEAD and index, and for every
49 * submodule described in .gitmodules. The fields are as follows:
51 * - `rc` tracks the refcount of how many hash table entries in the
52 * git_submodule_cache there are for this submodule. It only comes into
53 * play if the name and path of the submodule differ.
55 * - `name` is the name of the submodule from .gitmodules.
56 * - `path` is the path to the submodule from the repo root. It is almost
57 * always the same as `name`.
58 * - `url` is the url for the submodule.
59 * - `update` is a git_submodule_update_t value - see gitmodules(5) update.
60 * - `update_default` is the update value from the config
61 * - `ignore` is a git_submodule_ignore_t value - see gitmodules(5) ignore.
62 * - `ignore_default` is the ignore value from the config
63 * - `fetch_recurse` is a git_submodule_recurse_t value - see gitmodules(5)
64 * fetchRecurseSubmodules.
65 * - `fetch_recurse_default` is the recurse value from the config
67 * - `repo` is the parent repository that contains this submodule.
68 * - `flags` after for internal use, tracking where this submodule has been
69 * found (head, index, config, workdir) and known status info, etc.
70 * - `head_oid` is the SHA1 for the submodule path in the repo HEAD.
71 * - `index_oid` is the SHA1 for the submodule recorded in the index.
72 * - `wd_oid` is the SHA1 for the HEAD of the checked out submodule.
74 * If the submodule has been added to .gitmodules but not yet git added,
75 * then the `index_oid` will be zero but still marked valid. If the
76 * submodule has been deleted, but the delete has not been committed yet,
77 * then the `index_oid` will be set, but the `url` will be NULL.
79 struct git_submodule
{
82 /* information from config */
84 char *path
; /* important: may just point to "name" string */
87 git_submodule_update_t update
;
88 git_submodule_update_t update_default
;
89 git_submodule_ignore_t ignore
;
90 git_submodule_ignore_t ignore_default
;
91 git_submodule_recurse_t fetch_recurse
;
92 git_submodule_recurse_t fetch_recurse_default
;
94 /* internal information */
102 /* Force revalidation of submodule data cache (alloc as needed) */
103 extern int git_submodule_cache_refresh(git_repository
*repo
);
105 /* Release all submodules */
106 extern void git_submodule_cache_free(git_repository
*repo
);
108 /* Additional flags on top of public GIT_SUBMODULE_STATUS values */
110 GIT_SUBMODULE_STATUS__WD_SCANNED
= (1u << 20),
111 GIT_SUBMODULE_STATUS__HEAD_OID_VALID
= (1u << 21),
112 GIT_SUBMODULE_STATUS__INDEX_OID_VALID
= (1u << 22),
113 GIT_SUBMODULE_STATUS__WD_OID_VALID
= (1u << 23),
114 GIT_SUBMODULE_STATUS__HEAD_NOT_SUBMODULE
= (1u << 24),
115 GIT_SUBMODULE_STATUS__INDEX_NOT_SUBMODULE
= (1u << 25),
116 GIT_SUBMODULE_STATUS__WD_NOT_SUBMODULE
= (1u << 26),
117 GIT_SUBMODULE_STATUS__INDEX_MULTIPLE_ENTRIES
= (1u << 27),
120 #define GIT_SUBMODULE_STATUS__CLEAR_INTERNAL(S) \
121 ((S) & ~(0xFFFFFFFFu << 20))
123 /* Internal lookup does not attempt to refresh cached data */
124 extern int git_submodule__lookup(
125 git_submodule
**out
, git_repository
*repo
, const char *path
);
127 /* Internal status fn returns status and optionally the various OIDs */
128 extern int git_submodule__status(
129 unsigned int *out_status
,
130 git_oid
*out_head_id
,
131 git_oid
*out_index_id
,
134 git_submodule_ignore_t ign
);
136 /* Open submodule repository as bare repo for quick HEAD check, etc. */
137 extern int git_submodule_open_bare(
138 git_repository
**repo
,
139 git_submodule
*submodule
);
141 extern int git_submodule_parse_ignore(
142 git_submodule_ignore_t
*out
, const char *value
);
143 extern int git_submodule_parse_update(
144 git_submodule_update_t
*out
, const char *value
);