summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorJunio C Hamano <gitster@pobox.com>2015-08-31 22:38:52 (GMT)
committerJunio C Hamano <gitster@pobox.com>2015-08-31 22:38:52 (GMT)
commit5a4f07b32207044eb8380f2893f807cc8ab9d58f (patch)
tree8860227eb2821a6e7d6d490cb31a4b32a28227ff /Documentation
parentfc9dfda1be25ab3bb311900c6cfbf59d6b6e224e (diff)
parent027771fcb153e0003bcb2d68e1838594a48b0161 (diff)
downloadgit-5a4f07b32207044eb8380f2893f807cc8ab9d58f.zip
git-5a4f07b32207044eb8380f2893f807cc8ab9d58f.tar.gz
git-5a4f07b32207044eb8380f2893f807cc8ab9d58f.tar.bz2
Merge branch 'hv/submodule-config'
The gitmodules API accessed from the C code learned to cache stuff lazily. * hv/submodule-config: submodule: allow erroneous values for the fetchRecurseSubmodules option submodule: use new config API for worktree configurations submodule: extract functions for config set and lookup submodule: implement a config API for lookup of .gitmodules values
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/technical/api-submodule-config.txt62
1 files changed, 62 insertions, 0 deletions
diff --git a/Documentation/technical/api-submodule-config.txt b/Documentation/technical/api-submodule-config.txt
new file mode 100644
index 0000000..941fa17
--- /dev/null
+++ b/Documentation/technical/api-submodule-config.txt
@@ -0,0 +1,62 @@
+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.