projects / thirdparty / git.git / blame
| 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 | ||
| f793b895 | 41 | `void submodule_free(struct repository *r)`:: |
| 959b5455 HV |
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. |