| Junio C Hamano | 3891e25 | 2015-08-31 23:06:13 | [diff] [blame] | 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 *commit_sha1, const char *path)`:: |
| 51 | |
| 52 | Lookup values for one submodule by its commit_sha1 and path. |
| 53 | |
| 54 | `const struct submodule *submodule_from_name(const unsigned char *commit_sha1, const char *name)`:: |
| 55 | |
| 56 | The same as above but lookup by name. |
| 57 | |
| 58 | If given the null_sha1 as commit_sha1 the local configuration of a |
| 59 | submodule will be returned (e.g. consolidated values from local git |
| 60 | configuration and the .gitmodules file in the worktree). |
| 61 | |
| 62 | For an example usage see test-submodule-config.c. |
