]>
Commit | Line | Data |
---|---|---|
1be9d84b HV |
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 | ||
2b2a5be3 | 9 | int handle_one_ref(const char *refname, const struct object_id *oid, |
1be9d84b HV |
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 | ||
419221c1 NTND |
35 | * Use `refs_` API for accessing submodules. The submodule ref store could |
36 | be obtained with `get_submodule_ref_store()`. | |
1be9d84b HV |
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" | |
2951add0 | 50 | if (add_submodule_odb(path)) |
1be9d84b HV |
51 | die("Error submodule '%s' not populated.", path); |
52 | ||
2951add0 | 53 | `add_submodule_odb()` will return zero on success. If you |
1be9d84b HV |
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 can not 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 | ---- |