1#ifndef NOTES_H 2#define NOTES_H 3 4/* 5 * Function type for combining two notes annotating the same object. 6 * 7 * When adding a new note annotating the same object as an existing note, it is 8 * up to the caller to decide how to combine the two notes. The decision is 9 * made by passing in a function of the following form. The function accepts 10 * two SHA1s -- of the existing note and the new note, respectively. The 11 * function then combines the notes in whatever way it sees fit, and writes the 12 * resulting SHA1 into the first SHA1 argument (cur_sha1). A non-zero return 13 * value indicates failure. 14 * 15 * The two given SHA1s must both be non-NULL and different from each other. 16 * 17 * The default combine_notes function (you get this when passing NULL) is 18 * combine_notes_concatenate(), which appends the contents of the new note to 19 * the contents of the existing note. 20 */ 21typedefintcombine_notes_fn(unsigned char*cur_sha1,const unsigned char*new_sha1); 22 23/* Common notes combinators */ 24intcombine_notes_concatenate(unsigned char*cur_sha1,const unsigned char*new_sha1); 25intcombine_notes_overwrite(unsigned char*cur_sha1,const unsigned char*new_sha1); 26intcombine_notes_ignore(unsigned char*cur_sha1,const unsigned char*new_sha1); 27 28/* 29 * Notes tree object 30 * 31 * Encapsulates the internal notes tree structure associated with a notes ref. 32 * Whenever a struct notes_tree pointer is required below, you may pass NULL in 33 * order to use the default/internal notes tree. E.g. you only need to pass a 34 * non-NULL value if you need to refer to several different notes trees 35 * simultaneously. 36 */ 37externstruct notes_tree { 38struct int_node *root; 39char*ref; 40 combine_notes_fn *combine_notes; 41int initialized; 42} default_notes_tree; 43 44/* 45 * Flags controlling behaviour of notes tree initialization 46 * 47 * Default behaviour is to initialize the notes tree from the tree object 48 * specified by the given (or default) notes ref. 49 */ 50#define NOTES_INIT_EMPTY 1 51 52/* 53 * Initialize the given notes_tree with the notes tree structure at the given 54 * ref. If given ref is NULL, the value of the $GIT_NOTES_REF environment 55 * variable is used, and if that is missing, the default notes ref is used 56 * ("refs/notes/commits"). 57 * 58 * If you need to re-intialize a notes_tree structure (e.g. when switching from 59 * one notes ref to another), you must first de-initialize the notes_tree 60 * structure by calling free_notes(struct notes_tree *). 61 * 62 * If you pass t == NULL, the default internal notes_tree will be initialized. 63 * 64 * The combine_notes function that is passed becomes the default combine_notes 65 * function for the given notes_tree. If NULL is passed, the default 66 * combine_notes function is combine_notes_concatenate(). 67 * 68 * Precondition: The notes_tree structure is zeroed (this can be achieved with 69 * memset(t, 0, sizeof(struct notes_tree))) 70 */ 71voidinit_notes(struct notes_tree *t,const char*notes_ref, 72 combine_notes_fn combine_notes,int flags); 73 74/* 75 * Add the given note object to the given notes_tree structure 76 * 77 * IMPORTANT: The changes made by add_note() to the given notes_tree structure 78 * are not persistent until a subsequent call to write_notes_tree() returns 79 * zero. 80 */ 81voidadd_note(struct notes_tree *t,const unsigned char*object_sha1, 82const unsigned char*note_sha1, combine_notes_fn combine_notes); 83 84/* 85 * Remove the given note object from the given notes_tree structure 86 * 87 * IMPORTANT: The changes made by remove_note() to the given notes_tree 88 * structure are not persistent until a subsequent call to write_notes_tree() 89 * returns zero. 90 */ 91voidremove_note(struct notes_tree *t,const unsigned char*object_sha1); 92 93/* 94 * Get the note object SHA1 containing the note data for the given object 95 * 96 * Return NULL if the given object has no notes. 97 */ 98const unsigned char*get_note(struct notes_tree *t, 99const unsigned char*object_sha1); 100 101/* 102 * Flags controlling behaviour of for_each_note() 103 * 104 * Default behaviour of for_each_note() is to traverse every single note object 105 * in the given notes tree, unpacking subtree entries along the way. 106 * The following flags can be used to alter the default behaviour: 107 * 108 * - DONT_UNPACK_SUBTREES causes for_each_note() NOT to unpack and recurse into 109 * subtree entries while traversing the notes tree. This causes notes within 110 * those subtrees NOT to be passed to the callback. Use this flag if you 111 * don't want to traverse _all_ notes, but only want to traverse the parts 112 * of the notes tree that have already been unpacked (this includes at least 113 * all notes that have been added/changed). 114 * 115 * - YIELD_SUBTREES causes any subtree entries that are encountered to be 116 * passed to the callback, before recursing into them. Subtree entries are 117 * not note objects, but represent intermediate directories in the notes 118 * tree. When passed to the callback, subtree entries will have a trailing 119 * slash in their path, which the callback may use to differentiate between 120 * note entries and subtree entries. Note that already-unpacked subtree 121 * entries are not part of the notes tree, and will therefore not be yielded. 122 * If this flag is used together with DONT_UNPACK_SUBTREES, for_each_note() 123 * will yield the subtree entry, but not recurse into it. 124 */ 125#define FOR_EACH_NOTE_DONT_UNPACK_SUBTREES 1 126#define FOR_EACH_NOTE_YIELD_SUBTREES 2 127 128/* 129 * Invoke the specified callback function for each note in the given notes_tree 130 * 131 * If the callback returns nonzero, the note walk is aborted, and the return 132 * value from the callback is returned from for_each_note(). Hence, a zero 133 * return value from for_each_note() indicates that all notes were walked 134 * successfully. 135 * 136 * IMPORTANT: The callback function is NOT allowed to change the notes tree. 137 * In other words, the following functions can NOT be invoked (on the current 138 * notes tree) from within the callback: 139 * - add_note() 140 * - remove_note() 141 * - free_notes() 142 */ 143typedefinteach_note_fn(const unsigned char*object_sha1, 144const unsigned char*note_sha1,char*note_path, 145void*cb_data); 146intfor_each_note(struct notes_tree *t,int flags, each_note_fn fn, 147void*cb_data); 148 149/* 150 * Write the given notes_tree structure to the object database 151 * 152 * Creates a new tree object encapsulating the current state of the given 153 * notes_tree, and stores its SHA1 into the 'result' argument. 154 * 155 * Returns zero on success, non-zero on failure. 156 * 157 * IMPORTANT: Changes made to the given notes_tree are not persistent until 158 * this function has returned zero. Please also remember to create a 159 * corresponding commit object, and update the appropriate notes ref. 160 */ 161intwrite_notes_tree(struct notes_tree *t,unsigned char*result); 162 163/* 164 * Free (and de-initialize) the given notes_tree structure 165 * 166 * IMPORTANT: Changes made to the given notes_tree since the last, successful 167 * call to write_notes_tree() will be lost. 168 */ 169voidfree_notes(struct notes_tree *t); 170 171/* Flags controlling how notes are formatted */ 172#define NOTES_SHOW_HEADER 1 173#define NOTES_INDENT 2 174 175/* 176 * Fill the given strbuf with the notes associated with the given object. 177 * 178 * If the given notes_tree structure is not initialized, it will be auto- 179 * initialized to the default value (see documentation for init_notes() above). 180 * If the given notes_tree is NULL, the internal/default notes_tree will be 181 * used instead. 182 * 183 * 'flags' is a bitwise combination of the above formatting flags. 184 */ 185voidformat_note(struct notes_tree *t,const unsigned char*object_sha1, 186struct strbuf *sb,const char*output_encoding,int flags); 187 188#endif