English ▾ Topics ▾ Latest version ▾ api-submodule-config last updated in 2.18.0

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 .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. 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().

Data Structures

struct submodule

This structure is used to return the information about one submodule for a certain revision. It is returned by the lookup functions.

Functions

void submodule_free(struct repository *r)

Use these to free the internally cached values.

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.

const struct submodule *submodule_from_path(const unsigned char *treeish_name, const char *path)

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.