1submodule config cache API 2========================== 3 4The submodule config cache API allows to read submodule 5configurations/information from specified revisions. Internally 6information is lazily read into a cache that is used to avoid 7unnecessary parsing of the same .gitmodule files. Lookups can be done by 8submodule path or name. 9 10Usage 11----- 12 13To initialize the cache with configurations from the worktree the caller 14typically first calls `gitmodules_config()` to read values from the 15worktree .gitmodules and then to overlay the local git config values 16`parse_submodule_config_option()` from the config parsing 17infrastructure. 18 19The caller can look up information about submodules by using the 20`submodule_from_path()` or `submodule_from_name()` functions. They return 21a `struct submodule` which contains the values. The API automatically 22initializes and allocates the needed infrastructure on-demand. If the 23caller does only want to lookup values from revisions the initialization 24can be skipped. 25 26If the internal cache might grow too big or when the caller is done with 27the API, all internally cached values can be freed with submodule_free(). 28 29Data 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 38Functions 39--------- 40 41`void submodule_free()`:: 42 43 Use these to free the internally cached values. 44 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 50`const struct submodule *submodule_from_path(const unsigned char *treeish_name, const char *path)`:: 51 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. 54 55`const struct submodule *submodule_from_name(const unsigned char *treeish_name, const char *name)`:: 56 57 The same as above but lookup by name. 58 59Whenever a submodule configuration is parsed in `parse_submodule_config_option` 60via e.g. `gitmodules_config()`, it will overwrite the null_sha1 entry. 61So in the normal case, when HEAD:.gitmodules is parsed first and then overlayed 62with the repository configuration, the null_sha1 entry contains the local 63configuration of a submodule (e.g. consolidated values from local git 64configuration and the .gitmodules file in the worktree). 65 66For an example usage see test-submodule-config.c.