refs: move doc to refs.h
Move the documentation from Documentation/technical/api-ref-iteration.txt to refs.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. Also documentation/technical/api-ref-iteration.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. 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
126c1ccefbeec2b3ba368146f057054352484ef4
2 files changed
+51
-78
Documentation/technical/api-ref-iteration.txt
deleted
-78
@@ -1,78 +0,0 @@
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 struct object_id *oid,
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
-* Use `refs_` API for accessing submodules. The submodule ref store could
36
- be obtained with `get_submodule_ref_store()`.
37
-
38
-* `for_each_rawref()` can be used to learn about broken ref and symref.
39
-
40
-* `for_each_reflog()` iterates each reflog file.
41
-
42
-Submodules
43
-----------
44
-
45
-If you want to iterate the refs of a submodule you first need to add the
46
-submodules object database. You can do this by a code-snippet like
47
-this:
48
-
49
- const char *path = "path/to/submodule"
50
- if (add_submodule_odb(path))
51
- die("Error submodule '%s' not populated.", path);
52
-
53
-`add_submodule_odb()` will return zero on success. If you
54
-do not do this you will get an error for each ref that it does not point
55
-to a valid object.
56
-
57
-Note: As a side-effect of this you cannot safely assume that all
58
-objects you lookup are available in superproject. All submodule objects
59
-will be available the same way as the superprojects objects.
60
-
61
-Example:
62
---------
63
-
64
-----
65
-static int handle_remote_ref(const char *refname,
66
- const unsigned char *sha1, int flags, void *cb_data)
67
-{
68
- struct strbuf *output = cb_data;
69
- strbuf_addf(output, "%s\n", refname);
70
- return 0;
71
-}
72
-
73
-...
74
-
75
- struct strbuf output = STRBUF_INIT;
76
- for_each_remote_ref(handle_remote_ref, &output);
77
- printf("%s", output.buf);
78
-----
refs.h
+51
@@ -310,19 +310,35 @@ int refs_for_each_branch_ref(struct ref_store *refs,
310
int refs_for_each_remote_ref(struct ref_store *refs,
311
each_ref_fn fn, void *cb_data);
312
313
+/* just iterates the head ref. */
314
int head_ref(each_ref_fn fn, void *cb_data);
315
+
316
+/* iterates all refs. */
317
int for_each_ref(each_ref_fn fn, void *cb_data);
318
+
319
+/**
320
+ * iterates all refs which have a defined prefix and strips that prefix from
321
+ * the passed variable refname.
322
+ */
323
int for_each_ref_in(const char *prefix, each_ref_fn fn, void *cb_data);
324
+
325
int refs_for_each_fullref_in(struct ref_store *refs, const char *prefix,
326
each_ref_fn fn, void *cb_data,
327
unsigned int broken);
328
int for_each_fullref_in(const char *prefix, each_ref_fn fn, void *cb_data,
329
unsigned int broken);
330
+
331
+/**
332
+ * iterate refs from the respective area.
333
+ */
334
int for_each_tag_ref(each_ref_fn fn, void *cb_data);
335
int for_each_branch_ref(each_ref_fn fn, void *cb_data);
336
int for_each_remote_ref(each_ref_fn fn, void *cb_data);
337
int for_each_replace_ref(struct repository *r, each_repo_ref_fn fn, void *cb_data);
338
+
339
+/* iterates all refs that match the specified glob pattern. */
340
int for_each_glob_ref(each_ref_fn fn, const char *pattern, void *cb_data);
341
+
342
int for_each_glob_ref_in(each_ref_fn fn, const char *pattern,
343
const char *prefix, void *cb_data);
344
@@ -791,6 +807,41 @@ int reflog_expire(const char *refname, const struct object_id *oid,
807
int ref_storage_backend_exists(const char *name);
808
809
struct ref_store *get_main_ref_store(struct repository *r);
810
+
811
+/**
812
+ * Submodules
813
+ * ----------
814
+ *
815
+ * If you want to iterate the refs of a submodule you first need to add the
816
+ * submodules object database. You can do this by a code-snippet like
817
+ * this:
818
+ *
819
+ * const char *path = "path/to/submodule"
820
+ * if (add_submodule_odb(path))
821
+ * die("Error submodule '%s' not populated.", path);
822
+ *
823
+ * `add_submodule_odb()` will return zero on success. If you
824
+ * do not do this you will get an error for each ref that it does not point
825
+ * to a valid object.
826
+ *
827
+ * Note: As a side-effect of this you cannot safely assume that all
828
+ * objects you lookup are available in superproject. All submodule objects
829
+ * will be available the same way as the superprojects objects.
830
+ *
831
+ * Example:
832
+ * --------
833
+ *
834
+ * ----
835
+ * static int handle_remote_ref(const char *refname,
836
+ * const unsigned char *sha1, int flags, void *cb_data)
837
+ * {
838
+ * struct strbuf *output = cb_data;
839
+ * strbuf_addf(output, "%s\n", refname);
840
+ * return 0;
841
+ * }
842
+ *
843
+ */
844
+
845
/*
846
* Return the ref_store instance for the specified submodule. For the
847
* main repository, use submodule==NULL; such a call cannot fail. For