add technical documentation about ref iteration
Signed-off-by: Heiko Voigt <hvoigt@hvoigt.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Heiko Voigt committed
Aug 22, 2011 at 22:36 UTC
1be9d84b2ed18c2b2e2d6a459d2b6d48d5ab86e5
1 file changed
+81
Documentation/technical/api-ref-iteration.txt
new
+81
@@ -0,0 +1,81 @@
1
+ref iteration API
2
+=================
3
+
4
+
5
+Iteration of refs is done by using an iterate function which will call a
6
+callback function for every ref. The callback function has this
7
+signature:
8
+
9
+ int handle_one_ref(const char *refname, const unsigned char *sha1,
10
+ int flags, void *cb_data);
11
+
12
+There are different kinds of iterate functions which all take a
13
+callback of this type. The callback is then called for each found ref
14
+until the callback returns nonzero. The returned value is then also
15
+returned by the iterate function.
16
+
17
+Iteration functions
18
+-------------------
19
+
20
+* `head_ref()` just iterates the head ref.
21
+
22
+* `for_each_ref()` iterates all refs.
23
+
24
+* `for_each_ref_in()` iterates all refs which have a defined prefix and
25
+ strips that prefix from the passed variable refname.
26
+
27
+* `for_each_tag_ref()`, `for_each_branch_ref()`, `for_each_remote_ref()`,
28
+ `for_each_replace_ref()` iterate refs from the respective area.
29
+
30
+* `for_each_glob_ref()` iterates all refs that match the specified glob
31
+ pattern.
32
+
33
+* `for_each_glob_ref_in()` the previous and `for_each_ref_in()` combined.
34
+
35
+* `head_ref_submodule()`, `for_each_ref_submodule()`,
36
+ `for_each_ref_in_submodule()`, `for_each_tag_ref_submodule()`,
37
+ `for_each_branch_ref_submodule()`, `for_each_remote_ref_submodule()`
38
+ do the same as the functions descibed above but for a specified
39
+ submodule.
40
+
41
+* `for_each_rawref()` can be used to learn about broken ref and symref.
42
+
43
+* `for_each_reflog()` iterates each reflog file.
44
+
45
+Submodules
46
+----------
47
+
48
+If you want to iterate the refs of a submodule you first need to add the
49
+submodules object database. You can do this by a code-snippet like
50
+this:
51
+
52
+ const char *path = "path/to/submodule"
53
+ if (!add_submodule_odb(path))
54
+ die("Error submodule '%s' not populated.", path);
55
+
56
+`add_submodule_odb()` will return an non-zero value on success. If you
57
+do not do this you will get an error for each ref that it does not point
58
+to a valid object.
59
+
60
+Note: As a side-effect of this you can not safely assume that all
61
+objects you lookup are available in superproject. All submodule objects
62
+will be available the same way as the superprojects objects.
63
+
64
+Example:
65
+--------
66
+
67
+----
68
+static int handle_remote_ref(const char *refname,
69
+ const unsigned char *sha1, int flags, void *cb_data)
70
+{
71
+ struct strbuf *output = cb_data;
72
+ strbuf_addf(output, "%s\n", refname);
73
+ return 0;
74
+}
75
+
76
+...
77
+
78
+ struct strbuf output = STRBUF_INIT;
79
+ for_each_remote_ref(handle_remote_ref, &output);
80
+ printf("%s", output.buf);
81
+----