summaryrefslogtreecommitdiff
path: root/notes.h
diff options
context:
space:
mode:
authorJohan Herland <johan@herland.net>2010-02-13 22:28:16 +0100
committerJunio C Hamano <gitster@pobox.com>2010-02-13 19:36:12 -0800
commit73f77b909f87fcaece42ec50d8d0c1c35efbf947 (patch)
tree3f575fdda6a63fe2a437230d4e19eb9566da95a4 /notes.h
parent9b391f218a5b732a5a8abae87d3165e97fe2f6f6 (diff)
downloadgit-73f77b909f87fcaece42ec50d8d0c1c35efbf947.tar.gz
Notes API: for_each_note(): Traverse the entire notes tree with a callback
This includes a first attempt at creating an optimal fanout scheme (which is calculated on-the-fly, while traversing). Signed-off-by: Johan Herland <johan@herland.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Diffstat (limited to 'notes.h')
-rw-r--r--notes.h47
1 files changed, 47 insertions, 0 deletions
diff --git a/notes.h b/notes.h
index 0041aecae0..2131912902 100644
--- a/notes.h
+++ b/notes.h
@@ -35,6 +35,53 @@ void remove_note(const unsigned char *object_sha1);
*/
const unsigned char *get_note(const unsigned char *object_sha1);
+/*
+ * Flags controlling behaviour of for_each_note()
+ *
+ * Default behaviour of for_each_note() is to traverse every single note object
+ * in the notes tree, unpacking subtree entries along the way.
+ * The following flags can be used to alter the default behaviour:
+ *
+ * - DONT_UNPACK_SUBTREES causes for_each_note() NOT to unpack and recurse into
+ * subtree entries while traversing the notes tree. This causes notes within
+ * those subtrees NOT to be passed to the callback. Use this flag if you
+ * don't want to traverse _all_ notes, but only want to traverse the parts
+ * of the notes tree that have already been unpacked (this includes at least
+ * all notes that have been added/changed).
+ *
+ * - YIELD_SUBTREES causes any subtree entries that are encountered to be
+ * passed to the callback, before recursing into them. Subtree entries are
+ * not note objects, but represent intermediate directories in the notes
+ * tree. When passed to the callback, subtree entries will have a trailing
+ * slash in their path, which the callback may use to differentiate between
+ * note entries and subtree entries. Note that already-unpacked subtree
+ * entries are not part of the notes tree, and will therefore not be yielded.
+ * If this flag is used together with DONT_UNPACK_SUBTREES, for_each_note()
+ * will yield the subtree entry, but not recurse into it.
+ */
+#define FOR_EACH_NOTE_DONT_UNPACK_SUBTREES 1
+#define FOR_EACH_NOTE_YIELD_SUBTREES 2
+
+/*
+ * Invoke the specified callback function for each note
+ *
+ * If the callback returns nonzero, the note walk is aborted, and the return
+ * value from the callback is returned from for_each_note(). Hence, a zero
+ * return value from for_each_note() indicates that all notes were walked
+ * successfully.
+ *
+ * IMPORTANT: The callback function is NOT allowed to change the notes tree.
+ * In other words, the following functions can NOT be invoked (on the current
+ * notes tree) from within the callback:
+ * - add_note()
+ * - remove_note()
+ * - free_notes()
+ */
+typedef int each_note_fn(const unsigned char *object_sha1,
+ const unsigned char *note_sha1, char *note_path,
+ void *cb_data);
+int for_each_note(int flags, each_note_fn fn, void *cb_data);
+
/* Free (and de-initialize) the internal notes tree structure */
void free_notes(void);