From 885b797a4abe1fdfe7c4273caa34207d6e5e4760 Mon Sep 17 00:00:00 2001 From: Michael Haggerty Date: Mon, 22 Aug 2011 12:33:52 +0200 Subject: [PATCH 1/2] Do not use C++-style comments Detected by "gcc -std=iso9899:1990 ...". This patch applies against "maint". Signed-off-by: Michael Haggerty Signed-off-by: Junio C Hamano --- notes.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/notes.c b/notes.c index f6ce8489d3..93e9868d5d 100644 --- a/notes.c +++ b/notes.c @@ -1105,7 +1105,7 @@ int remove_note(struct notes_tree *t, const unsigned char *object_sha1) hashcpy(l.key_sha1, object_sha1); hashclr(l.val_sha1); note_tree_remove(t, t->root, 0, &l); - if (is_null_sha1(l.val_sha1)) // no note was removed + if (is_null_sha1(l.val_sha1)) /* no note was removed */ return 1; t->dirty = 1; return 0; From 1be9d84b2ed18c2b2e2d6a459d2b6d48d5ab86e5 Mon Sep 17 00:00:00 2001 From: Heiko Voigt Date: Mon, 22 Aug 2011 22:36:45 +0200 Subject: [PATCH 2/2] add technical documentation about ref iteration Signed-off-by: Heiko Voigt Signed-off-by: Junio C Hamano --- Documentation/technical/api-ref-iteration.txt | 81 +++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 Documentation/technical/api-ref-iteration.txt diff --git a/Documentation/technical/api-ref-iteration.txt b/Documentation/technical/api-ref-iteration.txt new file mode 100644 index 0000000000..dbbea95db7 --- /dev/null +++ b/Documentation/technical/api-ref-iteration.txt @@ -0,0 +1,81 @@ +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); +----