1ref iteration API 2================= 3 4 5Iteration of refs is done by using an iterate function which will call a 6callback function for every ref. The callback function has this 7signature: 8 9 int handle_one_ref(const char *refname, const struct object_id *oid, 10 int flags, void *cb_data); 11 12There are different kinds of iterate functions which all take a 13callback of this type. The callback is then called for each found ref 14until the callback returns nonzero. The returned value is then also 15returned by the iterate function. 16 17Iteration 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 42Submodules 43---------- 44 45If you want to iterate the refs of a submodule you first need to add the 46submodules object database. You can do this by a code-snippet like 47this: 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 54do not do this you will get an error for each ref that it does not point 55to a valid object. 56 57Note: As a side-effect of this you can not safely assume that all 58objects you lookup are available in superproject. All submodule objects 59will be available the same way as the superprojects objects. 60 61Example: 62-------- 63 64---- 65static 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----