You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
66 lines
2.4 KiB
66 lines
2.4 KiB
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 *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.
|
|
|