2009-10-09 10:21:57 +00:00
|
|
|
#ifndef NOTES_H
|
|
|
|
#define NOTES_H
|
|
|
|
|
2011-03-29 20:56:53 +00:00
|
|
|
#include "string-list.h"
|
|
|
|
|
2018-08-15 17:54:05 +00:00
|
|
|
struct object_id;
|
|
|
|
struct strbuf;
|
|
|
|
|
Refactor notes concatenation into a flexible interface for combining notes
When adding a note to an object that already has an existing note, the
current solution is to concatenate the contents of the two notes. However,
the caller may instead wish to _overwrite_ the existing note with the new
note, or maybe even _ignore_ the new note, and keep the existing one. There
might also be other ways of combining notes that are only known to the
caller.
Therefore, instead of unconditionally concatenating notes, we let the caller
specify how to combine notes, by passing in a pointer to a function for
combining notes. The caller may choose to implement its own function for
notes combining, but normally one of the following three conveniently
supplied notes combination functions will be sufficient:
- combine_notes_concatenate() combines the two notes by appending the
contents of the new note to the contents of the existing note.
- combine_notes_overwrite() replaces the existing note with the new note.
- combine_notes_ignore() keeps the existing note, and ignores the new note.
A combine_notes function can be passed to init_notes() to choose a default
combine_notes function for that notes tree. If NULL is given, the notes tree
falls back to combine_notes_concatenate() as the ultimate default.
A combine_notes function can also be passed directly to add_note(), to
control the notes combining behaviour for a note addition in particular.
If NULL is passed, the combine_notes function registered for the given
notes tree is used.
Signed-off-by: Johan Herland <johan@herland.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-02-13 21:28:19 +00:00
|
|
|
/*
|
|
|
|
* Function type for combining two notes annotating the same object.
|
|
|
|
*
|
|
|
|
* When adding a new note annotating the same object as an existing note, it is
|
|
|
|
* up to the caller to decide how to combine the two notes. The decision is
|
|
|
|
* made by passing in a function of the following form. The function accepts
|
2018-01-28 00:13:17 +00:00
|
|
|
* two object_ids -- of the existing note and the new note, respectively. The
|
Refactor notes concatenation into a flexible interface for combining notes
When adding a note to an object that already has an existing note, the
current solution is to concatenate the contents of the two notes. However,
the caller may instead wish to _overwrite_ the existing note with the new
note, or maybe even _ignore_ the new note, and keep the existing one. There
might also be other ways of combining notes that are only known to the
caller.
Therefore, instead of unconditionally concatenating notes, we let the caller
specify how to combine notes, by passing in a pointer to a function for
combining notes. The caller may choose to implement its own function for
notes combining, but normally one of the following three conveniently
supplied notes combination functions will be sufficient:
- combine_notes_concatenate() combines the two notes by appending the
contents of the new note to the contents of the existing note.
- combine_notes_overwrite() replaces the existing note with the new note.
- combine_notes_ignore() keeps the existing note, and ignores the new note.
A combine_notes function can be passed to init_notes() to choose a default
combine_notes function for that notes tree. If NULL is given, the notes tree
falls back to combine_notes_concatenate() as the ultimate default.
A combine_notes function can also be passed directly to add_note(), to
control the notes combining behaviour for a note addition in particular.
If NULL is passed, the combine_notes function registered for the given
notes tree is used.
Signed-off-by: Johan Herland <johan@herland.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-02-13 21:28:19 +00:00
|
|
|
* function then combines the notes in whatever way it sees fit, and writes the
|
2018-01-28 00:13:17 +00:00
|
|
|
* resulting oid into the first argument (cur_oid). A non-zero return
|
Refactor notes concatenation into a flexible interface for combining notes
When adding a note to an object that already has an existing note, the
current solution is to concatenate the contents of the two notes. However,
the caller may instead wish to _overwrite_ the existing note with the new
note, or maybe even _ignore_ the new note, and keep the existing one. There
might also be other ways of combining notes that are only known to the
caller.
Therefore, instead of unconditionally concatenating notes, we let the caller
specify how to combine notes, by passing in a pointer to a function for
combining notes. The caller may choose to implement its own function for
notes combining, but normally one of the following three conveniently
supplied notes combination functions will be sufficient:
- combine_notes_concatenate() combines the two notes by appending the
contents of the new note to the contents of the existing note.
- combine_notes_overwrite() replaces the existing note with the new note.
- combine_notes_ignore() keeps the existing note, and ignores the new note.
A combine_notes function can be passed to init_notes() to choose a default
combine_notes function for that notes tree. If NULL is given, the notes tree
falls back to combine_notes_concatenate() as the ultimate default.
A combine_notes function can also be passed directly to add_note(), to
control the notes combining behaviour for a note addition in particular.
If NULL is passed, the combine_notes function registered for the given
notes tree is used.
Signed-off-by: Johan Herland <johan@herland.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-02-13 21:28:19 +00:00
|
|
|
* value indicates failure.
|
|
|
|
*
|
2018-01-28 00:13:17 +00:00
|
|
|
* The two given object_ids shall both be non-NULL and different from each
|
|
|
|
* other. Either of them (but not both) may be == null_oid, which indicates an
|
|
|
|
* empty/non-existent note. If the resulting oid (cur_oid) is == null_oid,
|
2010-11-09 21:49:41 +00:00
|
|
|
* the note will be removed from the notes tree.
|
Refactor notes concatenation into a flexible interface for combining notes
When adding a note to an object that already has an existing note, the
current solution is to concatenate the contents of the two notes. However,
the caller may instead wish to _overwrite_ the existing note with the new
note, or maybe even _ignore_ the new note, and keep the existing one. There
might also be other ways of combining notes that are only known to the
caller.
Therefore, instead of unconditionally concatenating notes, we let the caller
specify how to combine notes, by passing in a pointer to a function for
combining notes. The caller may choose to implement its own function for
notes combining, but normally one of the following three conveniently
supplied notes combination functions will be sufficient:
- combine_notes_concatenate() combines the two notes by appending the
contents of the new note to the contents of the existing note.
- combine_notes_overwrite() replaces the existing note with the new note.
- combine_notes_ignore() keeps the existing note, and ignores the new note.
A combine_notes function can be passed to init_notes() to choose a default
combine_notes function for that notes tree. If NULL is given, the notes tree
falls back to combine_notes_concatenate() as the ultimate default.
A combine_notes function can also be passed directly to add_note(), to
control the notes combining behaviour for a note addition in particular.
If NULL is passed, the combine_notes function registered for the given
notes tree is used.
Signed-off-by: Johan Herland <johan@herland.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-02-13 21:28:19 +00:00
|
|
|
*
|
|
|
|
* 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.
|
|
|
|
*/
|
2018-01-28 00:13:17 +00:00
|
|
|
typedef int (*combine_notes_fn)(struct object_id *cur_oid,
|
|
|
|
const struct object_id *new_oid);
|
Refactor notes concatenation into a flexible interface for combining notes
When adding a note to an object that already has an existing note, the
current solution is to concatenate the contents of the two notes. However,
the caller may instead wish to _overwrite_ the existing note with the new
note, or maybe even _ignore_ the new note, and keep the existing one. There
might also be other ways of combining notes that are only known to the
caller.
Therefore, instead of unconditionally concatenating notes, we let the caller
specify how to combine notes, by passing in a pointer to a function for
combining notes. The caller may choose to implement its own function for
notes combining, but normally one of the following three conveniently
supplied notes combination functions will be sufficient:
- combine_notes_concatenate() combines the two notes by appending the
contents of the new note to the contents of the existing note.
- combine_notes_overwrite() replaces the existing note with the new note.
- combine_notes_ignore() keeps the existing note, and ignores the new note.
A combine_notes function can be passed to init_notes() to choose a default
combine_notes function for that notes tree. If NULL is given, the notes tree
falls back to combine_notes_concatenate() as the ultimate default.
A combine_notes function can also be passed directly to add_note(), to
control the notes combining behaviour for a note addition in particular.
If NULL is passed, the combine_notes function registered for the given
notes tree is used.
Signed-off-by: Johan Herland <johan@herland.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-02-13 21:28:19 +00:00
|
|
|
|
|
|
|
/* Common notes combinators */
|
2018-01-28 00:13:17 +00:00
|
|
|
int combine_notes_concatenate(struct object_id *cur_oid,
|
|
|
|
const struct object_id *new_oid);
|
|
|
|
int combine_notes_overwrite(struct object_id *cur_oid,
|
|
|
|
const struct object_id *new_oid);
|
|
|
|
int combine_notes_ignore(struct object_id *cur_oid,
|
|
|
|
const struct object_id *new_oid);
|
|
|
|
int combine_notes_cat_sort_uniq(struct object_id *cur_oid,
|
|
|
|
const struct object_id *new_oid);
|
Refactor notes concatenation into a flexible interface for combining notes
When adding a note to an object that already has an existing note, the
current solution is to concatenate the contents of the two notes. However,
the caller may instead wish to _overwrite_ the existing note with the new
note, or maybe even _ignore_ the new note, and keep the existing one. There
might also be other ways of combining notes that are only known to the
caller.
Therefore, instead of unconditionally concatenating notes, we let the caller
specify how to combine notes, by passing in a pointer to a function for
combining notes. The caller may choose to implement its own function for
notes combining, but normally one of the following three conveniently
supplied notes combination functions will be sufficient:
- combine_notes_concatenate() combines the two notes by appending the
contents of the new note to the contents of the existing note.
- combine_notes_overwrite() replaces the existing note with the new note.
- combine_notes_ignore() keeps the existing note, and ignores the new note.
A combine_notes function can be passed to init_notes() to choose a default
combine_notes function for that notes tree. If NULL is given, the notes tree
falls back to combine_notes_concatenate() as the ultimate default.
A combine_notes function can also be passed directly to add_note(), to
control the notes combining behaviour for a note addition in particular.
If NULL is passed, the combine_notes function registered for the given
notes tree is used.
Signed-off-by: Johan Herland <johan@herland.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-02-13 21:28:19 +00:00
|
|
|
|
2010-02-13 21:28:18 +00:00
|
|
|
/*
|
|
|
|
* Notes tree object
|
|
|
|
*
|
|
|
|
* Encapsulates the internal notes tree structure associated with a notes ref.
|
|
|
|
* Whenever a struct notes_tree pointer is required below, you may pass NULL in
|
|
|
|
* order to use the default/internal notes tree. E.g. you only need to pass a
|
|
|
|
* non-NULL value if you need to refer to several different notes trees
|
|
|
|
* simultaneously.
|
|
|
|
*/
|
|
|
|
extern struct notes_tree {
|
|
|
|
struct int_node *root;
|
Teach notes code to properly preserve non-notes in the notes tree
The note tree structure allows for non-note entries to coexist with note
entries in a notes tree. Although we certainly expect there to be very
few non-notes in a notes tree, we should still support them to a certain
degree.
This patch teaches the notes code to preserve non-notes when updating the
notes tree with write_notes_tree(). Non-notes are not affected by fanout
restructuring.
For non-notes to be handled correctly, we can no longer allow subtree
entries that do not match the fanout structure produced by the notes code
itself. This means that fanouts like 4/36, 6/34, 8/32, 4/4/32, etc. are
no longer recognized as note subtrees; only 2-based fanouts are allowed
(2/38, 2/2/36, 2/2/2/34, etc.). Since the notes code has never at any point
_produced_ non-2-based fanouts, it is highly unlikely that this change will
cause problems for anyone.
The patch also adds some tests verifying the correct handling of non-notes
in a notes tree.
Signed-off-by: Johan Herland <johan@herland.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-02-13 21:28:23 +00:00
|
|
|
struct non_note *first_non_note, *prev_non_note;
|
2010-02-13 21:28:18 +00:00
|
|
|
char *ref;
|
2015-10-08 02:54:43 +00:00
|
|
|
char *update_ref;
|
2010-06-23 19:40:19 +00:00
|
|
|
combine_notes_fn combine_notes;
|
2010-02-13 21:28:18 +00:00
|
|
|
int initialized;
|
2010-03-12 17:04:36 +00:00
|
|
|
int dirty;
|
2010-02-13 21:28:18 +00:00
|
|
|
} default_notes_tree;
|
|
|
|
|
2010-11-09 21:49:39 +00:00
|
|
|
/*
|
|
|
|
* 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);
|
|
|
|
|
2010-02-13 21:28:12 +00:00
|
|
|
/*
|
|
|
|
* Flags controlling behaviour of notes tree initialization
|
|
|
|
*
|
|
|
|
* Default behaviour is to initialize the notes tree from the tree object
|
|
|
|
* specified by the given (or default) notes ref.
|
|
|
|
*/
|
|
|
|
#define NOTES_INIT_EMPTY 1
|
|
|
|
|
2015-10-08 02:54:43 +00:00
|
|
|
/*
|
|
|
|
* By default, the notes tree is only readable, and the notes ref can be
|
|
|
|
* any treeish. The notes tree can however be made writable with this flag,
|
|
|
|
* in which case only strict ref names can be used.
|
|
|
|
*/
|
|
|
|
#define NOTES_INIT_WRITABLE 2
|
|
|
|
|
2010-02-13 21:28:12 +00:00
|
|
|
/*
|
2010-02-13 21:28:18 +00:00
|
|
|
* Initialize the given notes_tree with the notes tree structure at the given
|
2010-02-13 21:28:12 +00:00
|
|
|
* ref. If given ref is NULL, the value of the $GIT_NOTES_REF environment
|
|
|
|
* variable is used, and if that is missing, the default notes ref is used
|
|
|
|
* ("refs/notes/commits").
|
|
|
|
*
|
2013-07-29 08:18:21 +00:00
|
|
|
* If you need to re-initialize a notes_tree structure (e.g. when switching from
|
2010-02-13 21:28:18 +00:00
|
|
|
* one notes ref to another), you must first de-initialize the notes_tree
|
|
|
|
* structure by calling free_notes(struct notes_tree *).
|
|
|
|
*
|
|
|
|
* If you pass t == NULL, the default internal notes_tree will be initialized.
|
|
|
|
*
|
Refactor notes concatenation into a flexible interface for combining notes
When adding a note to an object that already has an existing note, the
current solution is to concatenate the contents of the two notes. However,
the caller may instead wish to _overwrite_ the existing note with the new
note, or maybe even _ignore_ the new note, and keep the existing one. There
might also be other ways of combining notes that are only known to the
caller.
Therefore, instead of unconditionally concatenating notes, we let the caller
specify how to combine notes, by passing in a pointer to a function for
combining notes. The caller may choose to implement its own function for
notes combining, but normally one of the following three conveniently
supplied notes combination functions will be sufficient:
- combine_notes_concatenate() combines the two notes by appending the
contents of the new note to the contents of the existing note.
- combine_notes_overwrite() replaces the existing note with the new note.
- combine_notes_ignore() keeps the existing note, and ignores the new note.
A combine_notes function can be passed to init_notes() to choose a default
combine_notes function for that notes tree. If NULL is given, the notes tree
falls back to combine_notes_concatenate() as the ultimate default.
A combine_notes function can also be passed directly to add_note(), to
control the notes combining behaviour for a note addition in particular.
If NULL is passed, the combine_notes function registered for the given
notes tree is used.
Signed-off-by: Johan Herland <johan@herland.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-02-13 21:28:19 +00:00
|
|
|
* The combine_notes function that is passed becomes the default combine_notes
|
|
|
|
* function for the given notes_tree. If NULL is passed, the default
|
|
|
|
* combine_notes function is combine_notes_concatenate().
|
|
|
|
*
|
2010-02-13 21:28:18 +00:00
|
|
|
* Precondition: The notes_tree structure is zeroed (this can be achieved with
|
|
|
|
* memset(t, 0, sizeof(struct notes_tree)))
|
2010-02-13 21:28:12 +00:00
|
|
|
*/
|
Refactor notes concatenation into a flexible interface for combining notes
When adding a note to an object that already has an existing note, the
current solution is to concatenate the contents of the two notes. However,
the caller may instead wish to _overwrite_ the existing note with the new
note, or maybe even _ignore_ the new note, and keep the existing one. There
might also be other ways of combining notes that are only known to the
caller.
Therefore, instead of unconditionally concatenating notes, we let the caller
specify how to combine notes, by passing in a pointer to a function for
combining notes. The caller may choose to implement its own function for
notes combining, but normally one of the following three conveniently
supplied notes combination functions will be sufficient:
- combine_notes_concatenate() combines the two notes by appending the
contents of the new note to the contents of the existing note.
- combine_notes_overwrite() replaces the existing note with the new note.
- combine_notes_ignore() keeps the existing note, and ignores the new note.
A combine_notes function can be passed to init_notes() to choose a default
combine_notes function for that notes tree. If NULL is given, the notes tree
falls back to combine_notes_concatenate() as the ultimate default.
A combine_notes function can also be passed directly to add_note(), to
control the notes combining behaviour for a note addition in particular.
If NULL is passed, the combine_notes function registered for the given
notes tree is used.
Signed-off-by: Johan Herland <johan@herland.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-02-13 21:28:19 +00:00
|
|
|
void init_notes(struct notes_tree *t, const char *notes_ref,
|
|
|
|
combine_notes_fn combine_notes, int flags);
|
2010-02-13 21:28:12 +00:00
|
|
|
|
2010-02-13 21:28:17 +00:00
|
|
|
/*
|
2010-02-13 21:28:18 +00:00
|
|
|
* Add the given note object to the given notes_tree structure
|
2010-02-13 21:28:17 +00:00
|
|
|
*
|
2010-11-09 21:49:41 +00:00
|
|
|
* 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.
|
|
|
|
*
|
2010-11-14 23:52:26 +00:00
|
|
|
* Returns zero on success; non-zero means combine_notes failed.
|
|
|
|
*
|
2010-02-13 21:28:18 +00:00
|
|
|
* IMPORTANT: The changes made by add_note() to the given notes_tree structure
|
2010-02-13 21:28:17 +00:00
|
|
|
* are not persistent until a subsequent call to write_notes_tree() returns
|
|
|
|
* zero.
|
|
|
|
*/
|
2017-05-30 17:30:43 +00:00
|
|
|
int add_note(struct notes_tree *t, const struct object_id *object_oid,
|
|
|
|
const struct object_id *note_oid, combine_notes_fn combine_notes);
|
2010-02-13 21:28:13 +00:00
|
|
|
|
2010-02-13 21:28:17 +00:00
|
|
|
/*
|
2010-02-13 21:28:18 +00:00
|
|
|
* Remove the given note object from the given notes_tree structure
|
2010-02-13 21:28:17 +00:00
|
|
|
*
|
2010-02-13 21:28:18 +00:00
|
|
|
* IMPORTANT: The changes made by remove_note() to the given notes_tree
|
2010-02-13 21:28:17 +00:00
|
|
|
* structure are not persistent until a subsequent call to write_notes_tree()
|
|
|
|
* returns zero.
|
2010-08-31 15:56:50 +00:00
|
|
|
*
|
|
|
|
* Return 0 if a note was removed; 1 if there was no note to remove.
|
2010-02-13 21:28:17 +00:00
|
|
|
*/
|
2010-08-31 15:56:50 +00:00
|
|
|
int remove_note(struct notes_tree *t, const unsigned char *object_sha1);
|
2010-02-13 21:28:14 +00:00
|
|
|
|
2010-02-13 21:28:15 +00:00
|
|
|
/*
|
|
|
|
* Get the note object SHA1 containing the note data for the given object
|
|
|
|
*
|
|
|
|
* Return NULL if the given object has no notes.
|
|
|
|
*/
|
2017-05-30 17:30:40 +00:00
|
|
|
const struct object_id *get_note(struct notes_tree *t,
|
2017-05-30 17:30:43 +00:00
|
|
|
const struct object_id *object_oid);
|
2010-02-13 21:28:15 +00:00
|
|
|
|
2010-03-12 17:04:31 +00:00
|
|
|
/*
|
|
|
|
* Copy a note from one object to another in the given notes_tree.
|
|
|
|
*
|
2010-11-14 23:52:26 +00:00
|
|
|
* 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.
|
2010-11-09 21:49:38 +00:00
|
|
|
*
|
|
|
|
* 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.
|
2010-03-12 17:04:31 +00:00
|
|
|
*/
|
|
|
|
int copy_note(struct notes_tree *t,
|
2017-05-30 17:30:43 +00:00
|
|
|
const struct object_id *from_obj, const struct object_id *to_obj,
|
2010-11-14 23:52:26 +00:00
|
|
|
int force, combine_notes_fn combine_notes);
|
2010-03-12 17:04:31 +00:00
|
|
|
|
2010-02-13 21:28:16 +00:00
|
|
|
/*
|
|
|
|
* Flags controlling behaviour of for_each_note()
|
|
|
|
*
|
|
|
|
* Default behaviour of for_each_note() is to traverse every single note object
|
2010-02-13 21:28:18 +00:00
|
|
|
* in the given notes tree, unpacking subtree entries along the way.
|
2010-02-13 21:28:16 +00:00
|
|
|
* 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
|
|
|
|
|
|
|
|
/*
|
2010-02-13 21:28:18 +00:00
|
|
|
* Invoke the specified callback function for each note in the given notes_tree
|
2010-02-13 21:28:16 +00:00
|
|
|
*
|
|
|
|
* 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()
|
2010-11-09 21:49:38 +00:00
|
|
|
* - copy_note()
|
2010-02-13 21:28:16 +00:00
|
|
|
* - free_notes()
|
|
|
|
*/
|
2017-05-30 17:30:39 +00:00
|
|
|
typedef int each_note_fn(const struct object_id *object_oid,
|
|
|
|
const struct object_id *note_oid, char *note_path,
|
2010-02-13 21:28:16 +00:00
|
|
|
void *cb_data);
|
2010-02-13 21:28:18 +00:00
|
|
|
int for_each_note(struct notes_tree *t, int flags, each_note_fn fn,
|
|
|
|
void *cb_data);
|
2010-02-13 21:28:16 +00:00
|
|
|
|
2010-02-13 21:28:17 +00:00
|
|
|
/*
|
2010-02-13 21:28:18 +00:00
|
|
|
* Write the given notes_tree structure to the object database
|
2010-02-13 21:28:17 +00:00
|
|
|
*
|
2010-02-13 21:28:18 +00:00
|
|
|
* Creates a new tree object encapsulating the current state of the given
|
2018-01-28 00:13:18 +00:00
|
|
|
* notes_tree, and stores its object id into the 'result' argument.
|
2010-02-13 21:28:17 +00:00
|
|
|
*
|
|
|
|
* Returns zero on success, non-zero on failure.
|
|
|
|
*
|
2010-02-13 21:28:18 +00:00
|
|
|
* IMPORTANT: Changes made to the given notes_tree are not persistent until
|
|
|
|
* this function has returned zero. Please also remember to create a
|
|
|
|
* corresponding commit object, and update the appropriate notes ref.
|
2010-02-13 21:28:17 +00:00
|
|
|
*/
|
2018-01-28 00:13:18 +00:00
|
|
|
int write_notes_tree(struct notes_tree *t, struct object_id *result);
|
2010-02-13 21:28:17 +00:00
|
|
|
|
2010-05-14 21:42:07 +00:00
|
|
|
/* Flags controlling the operation of prune */
|
|
|
|
#define NOTES_PRUNE_VERBOSE 1
|
|
|
|
#define NOTES_PRUNE_DRYRUN 2
|
2010-02-13 21:28:27 +00:00
|
|
|
/*
|
|
|
|
* Remove all notes annotating non-existing objects from the given notes tree
|
|
|
|
*
|
|
|
|
* All notes in the given notes_tree that are associated with objects that no
|
|
|
|
* longer exist in the database, are removed from the notes tree.
|
|
|
|
*
|
|
|
|
* IMPORTANT: The changes made by prune_notes() to the given notes_tree
|
|
|
|
* structure are not persistent until a subsequent call to write_notes_tree()
|
|
|
|
* returns zero.
|
|
|
|
*/
|
2010-05-14 21:42:07 +00:00
|
|
|
void prune_notes(struct notes_tree *t, int flags);
|
2010-02-13 21:28:27 +00:00
|
|
|
|
2010-02-13 21:28:17 +00:00
|
|
|
/*
|
2010-02-13 21:28:18 +00:00
|
|
|
* Free (and de-initialize) the given notes_tree structure
|
2010-02-13 21:28:17 +00:00
|
|
|
*
|
2010-02-13 21:28:18 +00:00
|
|
|
* IMPORTANT: Changes made to the given notes_tree since the last, successful
|
2010-02-13 21:28:17 +00:00
|
|
|
* call to write_notes_tree() will be lost.
|
|
|
|
*/
|
2010-02-13 21:28:18 +00:00
|
|
|
void free_notes(struct notes_tree *t);
|
2009-10-09 10:22:06 +00:00
|
|
|
|
2010-03-12 17:04:26 +00:00
|
|
|
struct string_list;
|
|
|
|
|
|
|
|
struct display_notes_opt {
|
2011-03-29 20:57:27 +00:00
|
|
|
int use_default_notes;
|
2011-03-29 20:56:53 +00:00
|
|
|
struct string_list extra_notes_refs;
|
2010-03-12 17:04:26 +00:00
|
|
|
};
|
|
|
|
|
|
|
|
/*
|
|
|
|
* Load the notes machinery for displaying several notes trees.
|
|
|
|
*
|
|
|
|
* If 'opt' is not NULL, then it specifies additional settings for the
|
|
|
|
* displaying:
|
|
|
|
*
|
|
|
|
* - suppress_default_notes indicates that the notes from
|
|
|
|
* core.notesRef and notes.displayRef should not be loaded.
|
|
|
|
*
|
|
|
|
* - extra_notes_refs may contain a list of globs (in the same style
|
|
|
|
* as notes.displayRef) where notes should be loaded from.
|
|
|
|
*/
|
|
|
|
void init_display_notes(struct display_notes_opt *opt);
|
|
|
|
|
|
|
|
/*
|
|
|
|
* Append notes for the given 'object_sha1' from all trees set up by
|
|
|
|
* init_display_notes() to 'sb'. The 'flags' are a bitwise
|
|
|
|
* combination of
|
|
|
|
*
|
|
|
|
* - NOTES_SHOW_HEADER: add a 'Notes (refname):' header
|
|
|
|
*
|
|
|
|
* - NOTES_INDENT: indent the notes by 4 places
|
|
|
|
*
|
|
|
|
* You *must* call init_display_notes() before using this function.
|
|
|
|
*/
|
2017-05-30 17:30:41 +00:00
|
|
|
void format_display_notes(const struct object_id *object_oid,
|
2012-10-18 04:41:54 +00:00
|
|
|
struct strbuf *sb, const char *output_encoding, int raw);
|
2010-03-12 17:04:26 +00:00
|
|
|
|
|
|
|
/*
|
|
|
|
* Load the notes tree from each ref listed in 'refs'. The output is
|
|
|
|
* an array of notes_tree*, terminated by a NULL.
|
|
|
|
*/
|
2015-10-08 02:54:43 +00:00
|
|
|
struct notes_tree **load_notes_trees(struct string_list *refs, int flags);
|
2010-03-12 17:04:26 +00:00
|
|
|
|
|
|
|
/*
|
|
|
|
* Add all refs that match 'glob' to the 'list'.
|
|
|
|
*/
|
|
|
|
void string_list_add_refs_by_glob(struct string_list *list, const char *glob);
|
|
|
|
|
|
|
|
/*
|
|
|
|
* Add all refs from a colon-separated glob list 'globs' to the end of
|
|
|
|
* 'list'. Empty components are ignored. This helper is used to
|
|
|
|
* parse GIT_NOTES_DISPLAY_REF style environment variables.
|
|
|
|
*/
|
|
|
|
void string_list_add_refs_from_colon_sep(struct string_list *list,
|
|
|
|
const char *globs);
|
|
|
|
|
2011-03-29 20:55:32 +00:00
|
|
|
/* Expand inplace a note ref like "foo" or "notes/foo" into "refs/notes/foo" */
|
|
|
|
void expand_notes_ref(struct strbuf *sb);
|
|
|
|
|
2015-12-29 22:40:28 +00:00
|
|
|
/*
|
|
|
|
* Similar to expand_notes_ref, but will check whether the ref can be located
|
|
|
|
* via get_sha1 first, and only falls back to expand_notes_ref in the case
|
|
|
|
* where get_sha1 fails.
|
|
|
|
*/
|
|
|
|
void expand_loose_notes_ref(struct strbuf *sb);
|
|
|
|
|
2009-10-09 10:21:57 +00:00
|
|
|
#endif
|