path: root/Documentation/technical
diff options
authorHeiko Voigt <>2015-08-18 00:21:59 (GMT)
committerJunio C Hamano <>2015-08-19 18:43:10 (GMT)
commit851e18c3859ad0f9f7e91fdb4d6cce5a8272420b (patch)
tree174141bad5af8da81d0eb6272584eadfa1906c74 /Documentation/technical
parent0d9f282c943a0799999176a2d8291ecbad060389 (diff)
submodule: use new config API for worktree configurations
We remove the extracted functions and directly parse into and read out of the cache. This allows us to have one unified way of accessing submodule configuration values specific to single submodules. Regardless whether we need to access a configuration from history or from the worktree. Signed-off-by: Heiko Voigt <> Signed-off-by: Junio C Hamano <> Signed-off-by: Stefan Beller <> Signed-off-by: Junio C Hamano <>
Diffstat (limited to 'Documentation/technical')
1 files changed, 18 insertions, 1 deletions
diff --git a/Documentation/technical/api-submodule-config.txt b/Documentation/technical/api-submodule-config.txt
index 1fbde41..941fa17 100644
--- a/Documentation/technical/api-submodule-config.txt
+++ b/Documentation/technical/api-submodule-config.txt
@@ -10,10 +10,18 @@ submodule path or name.
+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
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.
+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().
@@ -34,6 +42,11 @@ Functions
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.
@@ -42,4 +55,8 @@ Functions
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.