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.

TEST_PROGRAMS_NEED_X += test-submodule-config

LIB_OBJS += submodule-config.o

#include "submodule-config.h"

#include "submodule-config.h"

#include "submodule-config.h"