]>
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 | ||
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()` | |
e1c3bf49 | 38 | do the same as the functions described above but for a specified |
1be9d84b HV |
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" | |
2951add0 | 53 | if (add_submodule_odb(path)) |
1be9d84b HV |
54 | die("Error submodule '%s' not populated.", path); |
55 | ||
2951add0 | 56 | `add_submodule_odb()` will return zero on success. If you |
1be9d84b HV |
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 | ---- |