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 struct object_id *oid,
                   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

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 zero 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);