6d16922798
"Can not" suggests one has the option to not do something, whereas "cannot" more strongly suggests something is disallowed or impossible. Noticed "can not", mistakenly used instead of "cannot" in git help glossary, then ran git grep 'can not' and found many other instances. Only files in the Documentation folder were modified. 'Can not' also occurs in some source code comments and some test assertion messages, and there is an error message and translation "can not move directory into itself" which I may fix and submit separately from the documentation change. Also noticed and fixed "is does" in git help fetch, but there are no other occurrences of that typo according to git grep. Signed-off-by: Mark Rushakoff <mark.rushakoff@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
79 lines
2.3 KiB
Plaintext
79 lines
2.3 KiB
Plaintext
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.
|
|
|
|
* Use `refs_` API for accessing submodules. The submodule ref store could
|
|
be obtained with `get_submodule_ref_store()`.
|
|
|
|
* `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 cannot 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);
|
|
----
|