67 lines
2.4 KiB
Text
67 lines
2.4 KiB
Text
|
submodule config cache API
|
||
|
|
==========================
|
||
|
|
|
||
|
|
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.
|