notes.hon commit grep: recurse in-process using 'struct repository' (f9ee2fc)
   1#ifndef NOTES_H
   2#define NOTES_H
   3
   4#include "string-list.h"
   5
   6/*
   7 * Function type for combining two notes annotating the same object.
   8 *
   9 * When adding a new note annotating the same object as an existing note, it is
  10 * up to the caller to decide how to combine the two notes. The decision is
  11 * made by passing in a function of the following form. The function accepts
  12 * two SHA1s -- of the existing note and the new note, respectively. The
  13 * function then combines the notes in whatever way it sees fit, and writes the
  14 * resulting SHA1 into the first SHA1 argument (cur_sha1). A non-zero return
  15 * value indicates failure.
  16 *
  17 * The two given SHA1s shall both be non-NULL and different from each other.
  18 * Either of them (but not both) may be == null_sha1, which indicates an
  19 * empty/non-existent note. If the resulting SHA1 (cur_sha1) is == null_sha1,
  20 * the note will be removed from the notes tree.
  21 *
  22 * The default combine_notes function (you get this when passing NULL) is
  23 * combine_notes_concatenate(), which appends the contents of the new note to
  24 * the contents of the existing note.
  25 */
  26typedef int (*combine_notes_fn)(unsigned char *cur_sha1, const unsigned char *new_sha1);
  27
  28/* Common notes combinators */
  29int combine_notes_concatenate(unsigned char *cur_sha1, const unsigned char *new_sha1);
  30int combine_notes_overwrite(unsigned char *cur_sha1, const unsigned char *new_sha1);
  31int combine_notes_ignore(unsigned char *cur_sha1, const unsigned char *new_sha1);
  32int combine_notes_cat_sort_uniq(unsigned char *cur_sha1, const unsigned char *new_sha1);
  33
  34/*
  35 * Notes tree object
  36 *
  37 * Encapsulates the internal notes tree structure associated with a notes ref.
  38 * Whenever a struct notes_tree pointer is required below, you may pass NULL in
  39 * order to use the default/internal notes tree. E.g. you only need to pass a
  40 * non-NULL value if you need to refer to several different notes trees
  41 * simultaneously.
  42 */
  43extern struct notes_tree {
  44        struct int_node *root;
  45        struct non_note *first_non_note, *prev_non_note;
  46        char *ref;
  47        char *update_ref;
  48        combine_notes_fn combine_notes;
  49        int initialized;
  50        int dirty;
  51} default_notes_tree;
  52
  53/*
  54 * Return the default notes ref.
  55 *
  56 * The default notes ref is the notes ref that is used when notes_ref == NULL
  57 * is passed to init_notes().
  58 *
  59 * This the first of the following to be defined:
  60 * 1. The '--ref' option to 'git notes', if given
  61 * 2. The $GIT_NOTES_REF environment variable, if set
  62 * 3. The value of the core.notesRef config variable, if set
  63 * 4. GIT_NOTES_DEFAULT_REF (i.e. "refs/notes/commits")
  64 */
  65const char *default_notes_ref(void);
  66
  67/*
  68 * Flags controlling behaviour of notes tree initialization
  69 *
  70 * Default behaviour is to initialize the notes tree from the tree object
  71 * specified by the given (or default) notes ref.
  72 */
  73#define NOTES_INIT_EMPTY 1
  74
  75/*
  76 * By default, the notes tree is only readable, and the notes ref can be
  77 * any treeish. The notes tree can however be made writable with this flag,
  78 * in which case only strict ref names can be used.
  79 */
  80#define NOTES_INIT_WRITABLE 2
  81
  82/*
  83 * Initialize the given notes_tree with the notes tree structure at the given
  84 * ref. If given ref is NULL, the value of the $GIT_NOTES_REF environment
  85 * variable is used, and if that is missing, the default notes ref is used
  86 * ("refs/notes/commits").
  87 *
  88 * If you need to re-initialize a notes_tree structure (e.g. when switching from
  89 * one notes ref to another), you must first de-initialize the notes_tree
  90 * structure by calling free_notes(struct notes_tree *).
  91 *
  92 * If you pass t == NULL, the default internal notes_tree will be initialized.
  93 *
  94 * The combine_notes function that is passed becomes the default combine_notes
  95 * function for the given notes_tree. If NULL is passed, the default
  96 * combine_notes function is combine_notes_concatenate().
  97 *
  98 * Precondition: The notes_tree structure is zeroed (this can be achieved with
  99 * memset(t, 0, sizeof(struct notes_tree)))
 100 */
 101void init_notes(struct notes_tree *t, const char *notes_ref,
 102                combine_notes_fn combine_notes, int flags);
 103
 104/*
 105 * Add the given note object to the given notes_tree structure
 106 *
 107 * If there already exists a note for the given object_sha1, the given
 108 * combine_notes function is invoked to break the tie. If not given (i.e.
 109 * combine_notes == NULL), the default combine_notes function for the given
 110 * notes_tree is used.
 111 *
 112 * Passing note_sha1 == null_sha1 indicates the addition of an
 113 * empty/non-existent note. This is a (potentially expensive) no-op unless
 114 * there already exists a note for the given object_sha1, AND combining that
 115 * note with the empty note (using the given combine_notes function) results
 116 * in a new/changed note.
 117 *
 118 * Returns zero on success; non-zero means combine_notes failed.
 119 *
 120 * IMPORTANT: The changes made by add_note() to the given notes_tree structure
 121 * are not persistent until a subsequent call to write_notes_tree() returns
 122 * zero.
 123 */
 124int add_note(struct notes_tree *t, const struct object_id *object_oid,
 125                const struct object_id *note_oid, combine_notes_fn combine_notes);
 126
 127/*
 128 * Remove the given note object from the given notes_tree structure
 129 *
 130 * IMPORTANT: The changes made by remove_note() to the given notes_tree
 131 * structure are not persistent until a subsequent call to write_notes_tree()
 132 * returns zero.
 133 *
 134 * Return 0 if a note was removed; 1 if there was no note to remove.
 135 */
 136int remove_note(struct notes_tree *t, const unsigned char *object_sha1);
 137
 138/*
 139 * Get the note object SHA1 containing the note data for the given object
 140 *
 141 * Return NULL if the given object has no notes.
 142 */
 143const struct object_id *get_note(struct notes_tree *t,
 144                const struct object_id *object_oid);
 145
 146/*
 147 * Copy a note from one object to another in the given notes_tree.
 148 *
 149 * Returns 1 if the to_obj already has a note and 'force' is false. Otherwise,
 150 * returns non-zero if 'force' is true, but the given combine_notes function
 151 * failed to combine from_obj's note with to_obj's existing note.
 152 * Returns zero on success.
 153 *
 154 * IMPORTANT: The changes made by copy_note() to the given notes_tree structure
 155 * are not persistent until a subsequent call to write_notes_tree() returns
 156 * zero.
 157 */
 158int copy_note(struct notes_tree *t,
 159              const struct object_id *from_obj, const struct object_id *to_obj,
 160              int force, combine_notes_fn combine_notes);
 161
 162/*
 163 * Flags controlling behaviour of for_each_note()
 164 *
 165 * Default behaviour of for_each_note() is to traverse every single note object
 166 * in the given notes tree, unpacking subtree entries along the way.
 167 * The following flags can be used to alter the default behaviour:
 168 *
 169 * - DONT_UNPACK_SUBTREES causes for_each_note() NOT to unpack and recurse into
 170 *   subtree entries while traversing the notes tree. This causes notes within
 171 *   those subtrees NOT to be passed to the callback. Use this flag if you
 172 *   don't want to traverse _all_ notes, but only want to traverse the parts
 173 *   of the notes tree that have already been unpacked (this includes at least
 174 *   all notes that have been added/changed).
 175 *
 176 * - YIELD_SUBTREES causes any subtree entries that are encountered to be
 177 *   passed to the callback, before recursing into them. Subtree entries are
 178 *   not note objects, but represent intermediate directories in the notes
 179 *   tree. When passed to the callback, subtree entries will have a trailing
 180 *   slash in their path, which the callback may use to differentiate between
 181 *   note entries and subtree entries. Note that already-unpacked subtree
 182 *   entries are not part of the notes tree, and will therefore not be yielded.
 183 *   If this flag is used together with DONT_UNPACK_SUBTREES, for_each_note()
 184 *   will yield the subtree entry, but not recurse into it.
 185 */
 186#define FOR_EACH_NOTE_DONT_UNPACK_SUBTREES 1
 187#define FOR_EACH_NOTE_YIELD_SUBTREES 2
 188
 189/*
 190 * Invoke the specified callback function for each note in the given notes_tree
 191 *
 192 * If the callback returns nonzero, the note walk is aborted, and the return
 193 * value from the callback is returned from for_each_note(). Hence, a zero
 194 * return value from for_each_note() indicates that all notes were walked
 195 * successfully.
 196 *
 197 * IMPORTANT: The callback function is NOT allowed to change the notes tree.
 198 * In other words, the following functions can NOT be invoked (on the current
 199 * notes tree) from within the callback:
 200 * - add_note()
 201 * - remove_note()
 202 * - copy_note()
 203 * - free_notes()
 204 */
 205typedef int each_note_fn(const struct object_id *object_oid,
 206                const struct object_id *note_oid, char *note_path,
 207                void *cb_data);
 208int for_each_note(struct notes_tree *t, int flags, each_note_fn fn,
 209                void *cb_data);
 210
 211/*
 212 * Write the given notes_tree structure to the object database
 213 *
 214 * Creates a new tree object encapsulating the current state of the given
 215 * notes_tree, and stores its SHA1 into the 'result' argument.
 216 *
 217 * Returns zero on success, non-zero on failure.
 218 *
 219 * IMPORTANT: Changes made to the given notes_tree are not persistent until
 220 * this function has returned zero. Please also remember to create a
 221 * corresponding commit object, and update the appropriate notes ref.
 222 */
 223int write_notes_tree(struct notes_tree *t, unsigned char *result);
 224
 225/* Flags controlling the operation of prune */
 226#define NOTES_PRUNE_VERBOSE 1
 227#define NOTES_PRUNE_DRYRUN 2
 228/*
 229 * Remove all notes annotating non-existing objects from the given notes tree
 230 *
 231 * All notes in the given notes_tree that are associated with objects that no
 232 * longer exist in the database, are removed from the notes tree.
 233 *
 234 * IMPORTANT: The changes made by prune_notes() to the given notes_tree
 235 * structure are not persistent until a subsequent call to write_notes_tree()
 236 * returns zero.
 237 */
 238void prune_notes(struct notes_tree *t, int flags);
 239
 240/*
 241 * Free (and de-initialize) the given notes_tree structure
 242 *
 243 * IMPORTANT: Changes made to the given notes_tree since the last, successful
 244 * call to write_notes_tree() will be lost.
 245 */
 246void free_notes(struct notes_tree *t);
 247
 248struct string_list;
 249
 250struct display_notes_opt {
 251        int use_default_notes;
 252        struct string_list extra_notes_refs;
 253};
 254
 255/*
 256 * Load the notes machinery for displaying several notes trees.
 257 *
 258 * If 'opt' is not NULL, then it specifies additional settings for the
 259 * displaying:
 260 *
 261 * - suppress_default_notes indicates that the notes from
 262 *   core.notesRef and notes.displayRef should not be loaded.
 263 *
 264 * - extra_notes_refs may contain a list of globs (in the same style
 265 *   as notes.displayRef) where notes should be loaded from.
 266 */
 267void init_display_notes(struct display_notes_opt *opt);
 268
 269/*
 270 * Append notes for the given 'object_sha1' from all trees set up by
 271 * init_display_notes() to 'sb'.  The 'flags' are a bitwise
 272 * combination of
 273 *
 274 * - NOTES_SHOW_HEADER: add a 'Notes (refname):' header
 275 *
 276 * - NOTES_INDENT: indent the notes by 4 places
 277 *
 278 * You *must* call init_display_notes() before using this function.
 279 */
 280void format_display_notes(const struct object_id *object_oid,
 281                          struct strbuf *sb, const char *output_encoding, int raw);
 282
 283/*
 284 * Load the notes tree from each ref listed in 'refs'.  The output is
 285 * an array of notes_tree*, terminated by a NULL.
 286 */
 287struct notes_tree **load_notes_trees(struct string_list *refs, int flags);
 288
 289/*
 290 * Add all refs that match 'glob' to the 'list'.
 291 */
 292void string_list_add_refs_by_glob(struct string_list *list, const char *glob);
 293
 294/*
 295 * Add all refs from a colon-separated glob list 'globs' to the end of
 296 * 'list'.  Empty components are ignored.  This helper is used to
 297 * parse GIT_NOTES_DISPLAY_REF style environment variables.
 298 */
 299void string_list_add_refs_from_colon_sep(struct string_list *list,
 300                                         const char *globs);
 301
 302/* Expand inplace a note ref like "foo" or "notes/foo" into "refs/notes/foo" */
 303void expand_notes_ref(struct strbuf *sb);
 304
 305/*
 306 * Similar to expand_notes_ref, but will check whether the ref can be located
 307 * via get_sha1 first, and only falls back to expand_notes_ref in the case
 308 * where get_sha1 fails.
 309 */
 310void expand_loose_notes_ref(struct strbuf *sb);
 311
 312#endif