Documentation / technical / api-submodule-config.txton commit Merge branch 'sb/unpack-trees-would-lose-submodule-message-update' (c8a8951)
   1submodule config cache API
   2==========================
   3
   4The submodule config cache API allows to read submodule
   5configurations/information from specified revisions. Internally
   6information is lazily read into a cache that is used to avoid
   7unnecessary parsing of the same .gitmodule files. Lookups can be done by
   8submodule path or name.
   9
  10Usage
  11-----
  12
  13To initialize the cache with configurations from the worktree the caller
  14typically first calls `gitmodules_config()` to read values from the
  15worktree .gitmodules and then to overlay the local git config values
  16`parse_submodule_config_option()` from the config parsing
  17infrastructure.
  18
  19The caller can look up information about submodules by using the
  20`submodule_from_path()` or `submodule_from_name()` functions. They return
  21a `struct submodule` which contains the values. The API automatically
  22initializes and allocates the needed infrastructure on-demand. If the
  23caller does only want to lookup values from revisions the initialization
  24can be skipped.
  25
  26If the internal cache might grow too big or when the caller is done with
  27the API, all internally cached values can be freed with submodule_free().
  28
  29Data 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
  38Functions
  39---------
  40
  41`void submodule_free()`::
  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
  59Whenever a submodule configuration is parsed in `parse_submodule_config_option`
  60via e.g. `gitmodules_config()`, it will overwrite the null_sha1 entry.
  61So in the normal case, when HEAD:.gitmodules is parsed first and then overlayed
  62with the repository configuration, the null_sha1 entry contains the local
  63configuration of a submodule (e.g. consolidated values from local git
  64configuration and the .gitmodules file in the worktree).
  65
  66For an example usage see test-submodule-config.c.