[thirdparty/git.git] / Documentation / technical / api-submodule-config.txt

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.
Commit	Line	Data
	1	submodule config cache API
	2	==========================
	3
	4	The submodule config cache API allows to read submodule
	5	configurations/information from specified revisions. Internally
	6	information is lazily read into a cache that is used to avoid
	7	unnecessary parsing of the same .gitmodules files. Lookups can be done by
	8	submodule path or name.
	9
	10	Usage
	11	-----
	12
	13	To initialize the cache with configurations from the worktree the caller
	14	typically first calls `gitmodules_config()` to read values from the
	15	worktree .gitmodules and then to overlay the local git config values
	16	`parse_submodule_config_option()` from the config parsing
	17	infrastructure.
	18
	19	The caller can look up information about submodules by using the
	20	`submodule_from_path()` or `submodule_from_name()` functions. They return
	21	a `struct submodule` which contains the values. The API automatically
	22	initializes and allocates the needed infrastructure on-demand. If the
	23	caller does only want to lookup values from revisions the initialization
	24	can be skipped.
	25
	26	If the internal cache might grow too big or when the caller is done with
	27	the API, all internally cached values can be freed with submodule_free().
	28
	29	Data Structures
	30	---------------
	31
	32	`struct submodule`::
	33
	34	This structure is used to return the information about one
	35	submodule for a certain revision. It is returned by the lookup
	36	functions.
	37
	38	Functions
	39	---------
	40
	41	`void submodule_free(struct repository *r)`::
	42
	43	Use these to free the internally cached values.
	44
	45	`int parse_submodule_config_option(const char var, const char value)`::
	46
	47	Can be passed to the config parsing infrastructure to parse
	48	local (worktree) submodule configurations.
	49
	50	`const struct submodule submodule_from_path(const unsigned char treeish_name, const char *path)`::
	51
	52	Given a tree-ish in the superproject and a path, return the
	53	submodule that is bound at the path in the named tree.
	54
	55	`const struct submodule submodule_from_name(const unsigned char treeish_name, const char *name)`::
	56
	57	The same as above but lookup by name.
	58
	59	Whenever a submodule configuration is parsed in `parse_submodule_config_option`
	60	via e.g. `gitmodules_config()`, it will overwrite the null_sha1 entry.
	61	So in the normal case, when HEAD:.gitmodules is parsed first and then overlayed
	62	with the repository configuration, the null_sha1 entry contains the local
	63	configuration of a submodule (e.g. consolidated values from local git
	64	configuration and the .gitmodules file in the worktree).
	65
	66	For an example usage see test-submodule-config.c.