63 lines
2.1 KiB
Plaintext
63 lines
2.1 KiB
Plaintext
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 .gitmodule 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()`::
|
|
|
|
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 *commit_sha1, const char *path)`::
|
|
|
|
Lookup values for one submodule by its commit_sha1 and path.
|
|
|
|
`const struct submodule *submodule_from_name(const unsigned char *commit_sha1, const char *name)`::
|
|
|
|
The same as above but lookup by name.
|
|
|
|
If given the null_sha1 as commit_sha1 the local configuration of a
|
|
submodule will be returned (e.g. consolidated values from local git
|
|
configuration and the .gitmodules file in the worktree).
|
|
|
|
For an example usage see test-submodule-config.c.
|