summaryrefslogtreecommitdiff
path: root/refs
diff options
context:
space:
mode:
authorLibravatar Han-Wen Nienhuys <hanwen@google.com>2020-05-20 17:36:09 +0000
committerLibravatar Junio C Hamano <gitster@pobox.com>2020-05-20 10:39:02 -0700
commit84ee4ca10d7f598542eb2c1ea2cdf6199f9bdee1 (patch)
treedca44df73e73aa8c31e418b6444e9fa98730fe8f /refs
parentt: use update-ref and show-ref to reading/writing refs (diff)
downloadtgif-84ee4ca10d7f598542eb2c1ea2cdf6199f9bdee1.tar.xz
refs: improve documentation for ref iterator
Document some of the flag options in refs_ref_iterator_begin, and explain how ref_iterator_advance_fn should handle them. Signed-off-by: Han-Wen Nienhuys <hanwen@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Diffstat (limited to 'refs')
-rw-r--r--refs/refs-internal.h18
1 files changed, 15 insertions, 3 deletions
diff --git a/refs/refs-internal.h b/refs/refs-internal.h
index ff2436c0fb..4271362d26 100644
--- a/refs/refs-internal.h
+++ b/refs/refs-internal.h
@@ -347,9 +347,13 @@ int is_empty_ref_iterator(struct ref_iterator *ref_iterator);
/*
* Return an iterator that goes over each reference in `refs` for
* which the refname begins with prefix. If trim is non-zero, then
- * trim that many characters off the beginning of each refname. flags
- * can be DO_FOR_EACH_INCLUDE_BROKEN to include broken references in
- * the iteration. The output is ordered by refname.
+ * trim that many characters off the beginning of each refname.
+ * The output is ordered by refname. The following flags are supported:
+ *
+ * DO_FOR_EACH_INCLUDE_BROKEN: include broken references in
+ * the iteration.
+ *
+ * DO_FOR_EACH_PER_WORKTREE_ONLY: only produce REF_TYPE_PER_WORKTREE refs.
*/
struct ref_iterator *refs_ref_iterator_begin(
struct ref_store *refs,
@@ -438,6 +442,14 @@ void base_ref_iterator_free(struct ref_iterator *iter);
/* Virtual function declarations for ref_iterators: */
+/*
+ * backend-specific implementation of ref_iterator_advance. For symrefs, the
+ * function should set REF_ISSYMREF, and it should also dereference the symref
+ * to provide the OID referent. If DO_FOR_EACH_INCLUDE_BROKEN is set, symrefs
+ * with non-existent referents and refs pointing to non-existent object names
+ * should also be returned. If DO_FOR_EACH_PER_WORKTREE_ONLY, only
+ * REF_TYPE_PER_WORKTREE refs should be returned.
+ */
typedef int ref_iterator_advance_fn(struct ref_iterator *ref_iterator);
typedef int ref_iterator_peel_fn(struct ref_iterator *ref_iterator,