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>
Heba Waly committed
Nov 17, 2019 at 21:04 UTC
d95a77d05988ed1682c3e2bf1b94523341ef58b7
2 files changed
+37
-67
Documentation/technical/api-submodule-config.txt
deleted
-66
@@ -1,66 +0,0 @@
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 .gitmodules 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(struct repository *r)`::
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 *treeish_name, const char *path)`::
51
-
52
- Given a tree-ish in the superproject and a path, return the
53
- submodule that is bound at the path in the named tree.
54
-
55
-`const struct submodule *submodule_from_name(const unsigned char *treeish_name, const char *name)`::
56
-
57
- The same as above but lookup by name.
58
-
59
-Whenever a submodule configuration is parsed in `parse_submodule_config_option`
60
-via e.g. `gitmodules_config()`, it will overwrite the null_sha1 entry.
61
-So in the normal case, when HEAD:.gitmodules is parsed first and then overlayed
62
-with the repository configuration, the null_sha1 entry contains the local
63
-configuration of a submodule (e.g. consolidated values from local git
64
-configuration and the .gitmodules file in the worktree).
65
-
66
-For an example usage see test-submodule-config.c.
submodule-config.h
+37
-1
@@ -7,9 +7,31 @@
7
#include "submodule.h"
8
#include "strbuf.h"
9
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
+
32
/*
33
* 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.
35
*/
36
struct submodule {
37
const char *path;
@@ -41,13 +63,27 @@ int parse_update_recurse_submodules_arg(const char *opt, const char *arg);
63
int parse_push_recurse_submodules_arg(const char *opt, const char *arg);
64
void repo_read_gitmodules(struct repository *repo);
65
void gitmodules_config_oid(const struct object_id *commit_oid);
66
+
67
+/**
68
+ * Same as submodule_from_path but lookup by name.
69
+ */
70
const struct submodule *submodule_from_name(struct repository *r,
71
const struct object_id *commit_or_tree,
72
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
+ */
78
const struct submodule *submodule_from_path(struct repository *r,
79
const struct object_id *commit_or_tree,
80
const char *path);
81
+
82
+/**
83
+ * Use these to free the internally cached values.
84
+ */
85
void submodule_free(struct repository *r);
86
+
87
int print_config_from_gitmodules(struct repository *repo, const char *key);
88
int config_set_in_gitmodules_file_gently(const char *key, const char *value);
89