Documentation/technical/api-submodule-config.txt

   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 .gitmodule 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()`::
  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.