]>
Commit | Line | Data |
---|---|---|
959b5455 HV |
1 | submodule config cache API |
2 | ========================== | |
3 | ||
4 | The submodule config cache API allows to read submodule | |
5 | configurations/information from specified revisions. Internally | |
6 | information is lazily read into a cache that is used to avoid | |
5aea9fe6 | 7 | unnecessary parsing of the same .gitmodules files. Lookups can be done by |
959b5455 HV |
8 | submodule path or name. |
9 | ||
10 | Usage | |
11 | ----- | |
12 | ||
851e18c3 HV |
13 | To initialize the cache with configurations from the worktree the caller |
14 | typically first calls `gitmodules_config()` to read values from the | |
15 | worktree .gitmodules and then to overlay the local git config values | |
16 | `parse_submodule_config_option()` from the config parsing | |
17 | infrastructure. | |
18 | ||
959b5455 HV |
19 | The caller can look up information about submodules by using the |
20 | `submodule_from_path()` or `submodule_from_name()` functions. They return | |
21 | a `struct submodule` which contains the values. The API automatically | |
851e18c3 HV |
22 | initializes and allocates the needed infrastructure on-demand. If the |
23 | caller does only want to lookup values from revisions the initialization | |
24 | can be skipped. | |
959b5455 HV |
25 | |
26 | If the internal cache might grow too big or when the caller is done with | |
27 | the API, all internally cached values can be freed with submodule_free(). | |
28 | ||
29 | Data Structures | |
30 | --------------- | |
31 | ||
32 | `struct submodule`:: | |
33 | ||
34 | This structure is used to return the information about one | |
35 | submodule for a certain revision. It is returned by the lookup | |
36 | functions. | |
37 | ||
38 | Functions | |
39 | --------- | |
40 | ||
41 | `void submodule_free()`:: | |
42 | ||
43 | Use these to free the internally cached values. | |
44 | ||
851e18c3 HV |
45 | `int parse_submodule_config_option(const char *var, const char *value)`:: |
46 | ||
47 | Can be passed to the config parsing infrastructure to parse | |
48 | local (worktree) submodule configurations. | |
49 | ||
73c293bb | 50 | `const struct submodule *submodule_from_path(const unsigned char *treeish_name, const char *path)`:: |
959b5455 | 51 | |
73c293bb SB |
52 | Given a tree-ish in the superproject and a path, return the |
53 | submodule that is bound at the path in the named tree. | |
959b5455 | 54 | |
73c293bb | 55 | `const struct submodule *submodule_from_name(const unsigned char *treeish_name, const char *name)`:: |
959b5455 HV |
56 | |
57 | The same as above but lookup by name. | |
58 | ||
f2627d9b SB |
59 | Whenever a submodule configuration is parsed in `parse_submodule_config_option` |
60 | via e.g. `gitmodules_config()`, it will overwrite the null_sha1 entry. | |
61 | So in the normal case, when HEAD:.gitmodules is parsed first and then overlayed | |
62 | with the repository configuration, the null_sha1 entry contains the local | |
63 | configuration of a submodule (e.g. consolidated values from local git | |
851e18c3 HV |
64 | configuration and the .gitmodules file in the worktree). |
65 | ||
959b5455 | 66 | For an example usage see test-submodule-config.c. |