summaryrefslogtreecommitdiff
path: root/notes.h
diff options
context:
space:
mode:
Diffstat (limited to 'notes.h')
-rw-r--r--notes.h69
1 files changed, 59 insertions, 10 deletions
diff --git a/notes.h b/notes.h
index 9f59277c51..c716694b9e 100644
--- a/notes.h
+++ b/notes.h
@@ -1,6 +1,8 @@
#ifndef NOTES_H
#define NOTES_H
+#include "string-list.h"
+
/*
* Function type for combining two notes annotating the same object.
*
@@ -12,18 +14,22 @@
* resulting SHA1 into the first SHA1 argument (cur_sha1). A non-zero return
* value indicates failure.
*
- * The two given SHA1s must both be non-NULL and different from each other.
+ * The two given SHA1s shall both be non-NULL and different from each other.
+ * Either of them (but not both) may be == null_sha1, which indicates an
+ * empty/non-existent note. If the resulting SHA1 (cur_sha1) is == null_sha1,
+ * the note will be removed from the notes tree.
*
* The default combine_notes function (you get this when passing NULL) is
* combine_notes_concatenate(), which appends the contents of the new note to
* the contents of the existing note.
*/
-typedef int combine_notes_fn(unsigned char *cur_sha1, const unsigned char *new_sha1);
+typedef int (*combine_notes_fn)(unsigned char *cur_sha1, const unsigned char *new_sha1);
/* Common notes combinators */
int combine_notes_concatenate(unsigned char *cur_sha1, const unsigned char *new_sha1);
int combine_notes_overwrite(unsigned char *cur_sha1, const unsigned char *new_sha1);
int combine_notes_ignore(unsigned char *cur_sha1, const unsigned char *new_sha1);
+int combine_notes_cat_sort_uniq(unsigned char *cur_sha1, const unsigned char *new_sha1);
/*
* Notes tree object
@@ -38,12 +44,26 @@ extern struct notes_tree {
struct int_node *root;
struct non_note *first_non_note, *prev_non_note;
char *ref;
- combine_notes_fn *combine_notes;
+ combine_notes_fn combine_notes;
int initialized;
int dirty;
} default_notes_tree;
/*
+ * Return the default notes ref.
+ *
+ * The default notes ref is the notes ref that is used when notes_ref == NULL
+ * is passed to init_notes().
+ *
+ * This the first of the following to be defined:
+ * 1. The '--ref' option to 'git notes', if given
+ * 2. The $GIT_NOTES_REF environment variable, if set
+ * 3. The value of the core.notesRef config variable, if set
+ * 4. GIT_NOTES_DEFAULT_REF (i.e. "refs/notes/commits")
+ */
+const char *default_notes_ref(void);
+
+/*
* Flags controlling behaviour of notes tree initialization
*
* Default behaviour is to initialize the notes tree from the tree object
@@ -76,11 +96,24 @@ void init_notes(struct notes_tree *t, const char *notes_ref,
/*
* Add the given note object to the given notes_tree structure
*
+ * If there already exists a note for the given object_sha1, the given
+ * combine_notes function is invoked to break the tie. If not given (i.e.
+ * combine_notes == NULL), the default combine_notes function for the given
+ * notes_tree is used.
+ *
+ * Passing note_sha1 == null_sha1 indicates the addition of an
+ * empty/non-existent note. This is a (potentially expensive) no-op unless
+ * there already exists a note for the given object_sha1, AND combining that
+ * note with the empty note (using the given combine_notes function) results
+ * in a new/changed note.
+ *
+ * Returns zero on success; non-zero means combine_notes failed.
+ *
* IMPORTANT: The changes made by add_note() to the given notes_tree structure
* are not persistent until a subsequent call to write_notes_tree() returns
* zero.
*/
-void add_note(struct notes_tree *t, const unsigned char *object_sha1,
+int add_note(struct notes_tree *t, const unsigned char *object_sha1,
const unsigned char *note_sha1, combine_notes_fn combine_notes);
/*
@@ -89,8 +122,10 @@ void add_note(struct notes_tree *t, const unsigned char *object_sha1,
* IMPORTANT: The changes made by remove_note() to the given notes_tree
* structure are not persistent until a subsequent call to write_notes_tree()
* returns zero.
+ *
+ * Return 0 if a note was removed; 1 if there was no note to remove.
*/
-void remove_note(struct notes_tree *t, const unsigned char *object_sha1);
+int remove_note(struct notes_tree *t, const unsigned char *object_sha1);
/*
* Get the note object SHA1 containing the note data for the given object
@@ -103,11 +138,18 @@ const unsigned char *get_note(struct notes_tree *t,
/*
* Copy a note from one object to another in the given notes_tree.
*
- * Fails if the to_obj already has a note unless 'force' is true.
+ * Returns 1 if the to_obj already has a note and 'force' is false. Otherwise,
+ * returns non-zero if 'force' is true, but the given combine_notes function
+ * failed to combine from_obj's note with to_obj's existing note.
+ * Returns zero on success.
+ *
+ * IMPORTANT: The changes made by copy_note() to the given notes_tree structure
+ * are not persistent until a subsequent call to write_notes_tree() returns
+ * zero.
*/
int copy_note(struct notes_tree *t,
const unsigned char *from_obj, const unsigned char *to_obj,
- int force, combine_notes_fn combine_fn);
+ int force, combine_notes_fn combine_notes);
/*
* Flags controlling behaviour of for_each_note()
@@ -149,6 +191,7 @@ int copy_note(struct notes_tree *t,
* notes tree) from within the callback:
* - add_note()
* - remove_note()
+ * - copy_note()
* - free_notes()
*/
typedef int each_note_fn(const unsigned char *object_sha1,
@@ -171,6 +214,9 @@ int for_each_note(struct notes_tree *t, int flags, each_note_fn fn,
*/
int write_notes_tree(struct notes_tree *t, unsigned char *result);
+/* Flags controlling the operation of prune */
+#define NOTES_PRUNE_VERBOSE 1
+#define NOTES_PRUNE_DRYRUN 2
/*
* Remove all notes annotating non-existing objects from the given notes tree
*
@@ -181,7 +227,7 @@ int write_notes_tree(struct notes_tree *t, unsigned char *result);
* structure are not persistent until a subsequent call to write_notes_tree()
* returns zero.
*/
-void prune_notes(struct notes_tree *t);
+void prune_notes(struct notes_tree *t, int flags);
/*
* Free (and de-initialize) the given notes_tree structure
@@ -212,8 +258,8 @@ void format_note(struct notes_tree *t, const unsigned char *object_sha1,
struct string_list;
struct display_notes_opt {
- unsigned int suppress_default_notes:1;
- struct string_list *extra_notes_refs;
+ int use_default_notes;
+ struct string_list extra_notes_refs;
};
/*
@@ -263,4 +309,7 @@ void string_list_add_refs_by_glob(struct string_list *list, const char *glob);
void string_list_add_refs_from_colon_sep(struct string_list *list,
const char *globs);
+/* Expand inplace a note ref like "foo" or "notes/foo" into "refs/notes/foo" */
+void expand_notes_ref(struct strbuf *sb);
+
#endif