diff options
| -rw-r--r-- | Documentation/technical/api-submodule-config.txt | 66 | ||||
| -rw-r--r-- | submodule-config.h | 38 |
2 files changed, 37 insertions, 67 deletions
diff --git a/Documentation/technical/api-submodule-config.txt b/Documentation/technical/api-submodule-config.txt deleted file mode 100644 index fb06089..0000000 --- a/Documentation/technical/api-submodule-config.txt +++ /dev/null @@ -1,66 +0,0 @@ -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. diff --git a/submodule-config.h b/submodule-config.h index 1b4e2da..42918b5 100644 --- a/submodule-config.h +++ b/submodule-config.h @@ -7,9 +7,31 @@ #include "submodule.h" #include "strbuf.h" +/** + * 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 + * ----- + * + * 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(). + * + */ + /* * Submodule entry containing the information about a certain submodule - * in a certain revision. + * in a certain revision. It is returned by the lookup functions. */ struct submodule { const char *path; @@ -41,13 +63,27 @@ int parse_update_recurse_submodules_arg(const char *opt, const char *arg); int parse_push_recurse_submodules_arg(const char *opt, const char *arg); void repo_read_gitmodules(struct repository *repo); void gitmodules_config_oid(const struct object_id *commit_oid); + +/** + * Same as submodule_from_path but lookup by name. + */ const struct submodule *submodule_from_name(struct repository *r, const struct object_id *commit_or_tree, const char *name); + +/** + * 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_path(struct repository *r, const struct object_id *commit_or_tree, const char *path); + +/** + * Use these to free the internally cached values. + */ void submodule_free(struct repository *r); + int print_config_from_gitmodules(struct repository *repo, const char *key); int config_set_in_gitmodules_file_gently(const char *key, const char *value); |