# 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 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

- `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 described 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 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);