The submodule config cache API allows to read submodule
configurations/information from specified revisions. Internally
information is lazily read into a cache that is used to avoid
-unnecessary parsing of the same .gitmodule files. Lookups can be done by
+unnecessary parsing of the same .gitmodules files. Lookups can be done by
submodule path or name.
Usage
-----
+To initialize the cache with configurations from the worktree the caller
+typically first calls `gitmodules_config()` to read values from the
+worktree .gitmodules and then to overlay the local git config values
+`parse_submodule_config_option()` from the config parsing
+infrastructure.
+
The caller can look up information about submodules by using the
`submodule_from_path()` or `submodule_from_name()` functions. They return
a `struct submodule` which contains the values. The API automatically
-initializes and allocates the needed infrastructure on-demand.
+initializes and allocates the needed infrastructure on-demand. If the
+caller does only want to lookup values from revisions the initialization
+can be skipped.
If the internal cache might grow too big or when the caller is done with
the API, all internally cached values can be freed with submodule_free().
Functions
---------
-`void submodule_free()`::
+`void submodule_free(struct repository *r)`::
Use these to free the internally cached values.
-`const struct submodule *submodule_from_path(const unsigned char *commit_sha1, const char *path)`::
+`int parse_submodule_config_option(const char *var, const char *value)`::
+
+ Can be passed to the config parsing infrastructure to parse
+ local (worktree) submodule configurations.
- Lookup values for one submodule by its commit_sha1 and path.
+`const struct submodule *submodule_from_path(const unsigned char *treeish_name, const char *path)`::
-`const struct submodule *submodule_from_name(const unsigned char *commit_sha1, const char *name)`::
+ Given a tree-ish in the superproject and a path, return the
+ submodule that is bound at the path in the named tree.
+
+`const struct submodule *submodule_from_name(const unsigned char *treeish_name, const char *name)`::
The same as above but lookup by name.
+Whenever a submodule configuration is parsed in `parse_submodule_config_option`
+via e.g. `gitmodules_config()`, it will overwrite the null_sha1 entry.
+So in the normal case, when HEAD:.gitmodules is parsed first and then overlayed
+with the repository configuration, the null_sha1 entry contains the local
+configuration of a submodule (e.g. consolidated values from local git
+configuration and the .gitmodules file in the worktree).
+
For an example usage see test-submodule-config.c.