Skip to content

Commit d95a77d

Browse files
HebaWalygitster
HebaWaly
authored and
gitster
committed
submodule-config: move doc to submodule-config.h
Move the documentation from Documentation/technical/api-submodule-config.txt to submodule-config.h as it's easier for the developers to find the usage information beside the code instead of looking for it in another doc file. Documentation/technical/api-submodule-config.txt is removed because the information it has is now redundant and it'll be hard to keep it up to date and synchronized with the documentation in the header file. The documentation of parse_submodule_config_option() is discarded as the function was removed 2 years ago. Signed-off-by: Heba Waly <heba.waly@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
1 parent bbcfa30 commit d95a77d

File tree

2 files changed

+37
-67
lines changed

2 files changed

+37
-67
lines changed

‎Documentation/technical/api-submodule-config.txt‎

Lines changed: 0 additions & 66 deletions
This file was deleted.

‎submodule-config.h‎

Lines changed: 37 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,31 @@
77
#include "submodule.h"
88
#include "strbuf.h"
99

10+
/**
11+
* The submodule config cache API allows to read submodule
12+
* configurations/information from specified revisions. Internally
13+
* information is lazily read into a cache that is used to avoid
14+
* unnecessary parsing of the same .gitmodules files. Lookups can be done by
15+
* submodule path or name.
16+
*
17+
* Usage
18+
* -----
19+
*
20+
* The caller can look up information about submodules by using the
21+
* `submodule_from_path()` or `submodule_from_name()` functions. They return
22+
* a `struct submodule` which contains the values. The API automatically
23+
* initializes and allocates the needed infrastructure on-demand. If the
24+
* caller does only want to lookup values from revisions the initialization
25+
* can be skipped.
26+
*
27+
* If the internal cache might grow too big or when the caller is done with
28+
* the API, all internally cached values can be freed with submodule_free().
29+
*
30+
*/
31+
1032
/*
1133
* Submodule entry containing the information about a certain submodule
12-
* in a certain revision.
34+
* in a certain revision. It is returned by the lookup functions.
1335
*/
1436
struct submodule {
1537
const char *path;
@@ -41,13 +63,27 @@ int parse_update_recurse_submodules_arg(const char *opt, const char *arg);
4163
int parse_push_recurse_submodules_arg(const char *opt, const char *arg);
4264
void repo_read_gitmodules(struct repository *repo);
4365
void gitmodules_config_oid(const struct object_id *commit_oid);
66+
67+
/**
68+
* Same as submodule_from_path but lookup by name.
69+
*/
4470
const struct submodule *submodule_from_name(struct repository *r,
4571
const struct object_id *commit_or_tree,
4672
const char *name);
73+
74+
/**
75+
* Given a tree-ish in the superproject and a path, return the submodule that
76+
* is bound at the path in the named tree.
77+
*/
4778
const struct submodule *submodule_from_path(struct repository *r,
4879
const struct object_id *commit_or_tree,
4980
const char *path);
81+
82+
/**
83+
* Use these to free the internally cached values.
84+
*/
5085
void submodule_free(struct repository *r);
86+
5187
int print_config_from_gitmodules(struct repository *repo, const char *key);
5288
int config_set_in_gitmodules_file_gently(const char *key, const char *value);
5389

0 commit comments

Comments
 (0)