You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
81 lines
2.4 KiB
81 lines
2.4 KiB
ref iteration API |
|
================= |
|
|
|
|
|
Iteration of refs is done by using an iterate function which will call a |
|
callback function for every ref. The callback function has this |
|
signature: |
|
|
|
int handle_one_ref(const char *refname, const unsigned char *sha1, |
|
int flags, void *cb_data); |
|
|
|
There are different kinds of iterate functions which all take a |
|
callback of this type. The callback is then called for each found ref |
|
until the callback returns nonzero. The returned value is then also |
|
returned by the iterate function. |
|
|
|
Iteration functions |
|
------------------- |
|
|
|
* `head_ref()` just iterates the head ref. |
|
|
|
* `for_each_ref()` iterates all refs. |
|
|
|
* `for_each_ref_in()` iterates all refs which have a defined prefix and |
|
strips that prefix from the passed variable refname. |
|
|
|
* `for_each_tag_ref()`, `for_each_branch_ref()`, `for_each_remote_ref()`, |
|
`for_each_replace_ref()` iterate refs from the respective area. |
|
|
|
* `for_each_glob_ref()` iterates all refs that match the specified glob |
|
pattern. |
|
|
|
* `for_each_glob_ref_in()` the previous and `for_each_ref_in()` combined. |
|
|
|
* `head_ref_submodule()`, `for_each_ref_submodule()`, |
|
`for_each_ref_in_submodule()`, `for_each_tag_ref_submodule()`, |
|
`for_each_branch_ref_submodule()`, `for_each_remote_ref_submodule()` |
|
do the same as the functions descibed above but for a specified |
|
submodule. |
|
|
|
* `for_each_rawref()` can be used to learn about broken ref and symref. |
|
|
|
* `for_each_reflog()` iterates each reflog file. |
|
|
|
Submodules |
|
---------- |
|
|
|
If you want to iterate the refs of a submodule you first need to add the |
|
submodules object database. You can do this by a code-snippet like |
|
this: |
|
|
|
const char *path = "path/to/submodule" |
|
if (!add_submodule_odb(path)) |
|
die("Error submodule '%s' not populated.", path); |
|
|
|
`add_submodule_odb()` will return an non-zero value on success. If you |
|
do not do this you will get an error for each ref that it does not point |
|
to a valid object. |
|
|
|
Note: As a side-effect of this you can not safely assume that all |
|
objects you lookup are available in superproject. All submodule objects |
|
will be available the same way as the superprojects objects. |
|
|
|
Example: |
|
-------- |
|
|
|
---- |
|
static int handle_remote_ref(const char *refname, |
|
const unsigned char *sha1, int flags, void *cb_data) |
|
{ |
|
struct strbuf *output = cb_data; |
|
strbuf_addf(output, "%s\n", refname); |
|
return 0; |
|
} |
|
|
|
... |
|
|
|
struct strbuf output = STRBUF_INIT; |
|
for_each_remote_ref(handle_remote_ref, &output); |
|
printf("%s", output.buf); |
|
----
|
|
|