diff options
Diffstat (limited to 'include/git2/notes.h')
| -rw-r--r-- | include/git2/notes.h | 306 |
1 files changed, 306 insertions, 0 deletions
diff --git a/include/git2/notes.h b/include/git2/notes.h new file mode 100644 index 0000000..c135881 --- /dev/null +++ b/include/git2/notes.h @@ -0,0 +1,306 @@ +/* + * Copyright (C) the libgit2 contributors. All rights reserved. + * + * This file is part of libgit2, distributed under the GNU GPL v2 with + * a Linking Exception. For full terms see the included COPYING file. + */ +#ifndef INCLUDE_git_note_h__ +#define INCLUDE_git_note_h__ + +#include "oid.h" + +/** + * @file git2/notes.h + * @brief Git notes management routines + * @defgroup git_note Git notes management routines + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Callback for git_note_foreach. + * + * Receives: + * - blob_id: Oid of the blob containing the message + * - annotated_object_id: Oid of the git object being annotated + * - payload: Payload data passed to `git_note_foreach` + */ +typedef int GIT_CALLBACK(git_note_foreach_cb)( + const git_oid *blob_id, const git_oid *annotated_object_id, void *payload); + +/** + * note iterator + */ +typedef struct git_iterator git_note_iterator; + +/** + * Creates a new iterator for notes + * + * The iterator must be freed manually by the user. + * + * @param out pointer to the iterator + * @param repo repository where to look up the note + * @param notes_ref canonical name of the reference to use (optional); defaults to + * "refs/notes/commits" + * + * @return 0 or an error code + */ +GIT_EXTERN(int) git_note_iterator_new( + git_note_iterator **out, + git_repository *repo, + const char *notes_ref); + +/** + * Creates a new iterator for notes from a commit + * + * The iterator must be freed manually by the user. + * + * @param out pointer to the iterator + * @param notes_commit a pointer to the notes commit object + * + * @return 0 or an error code + */ +GIT_EXTERN(int) git_note_commit_iterator_new( + git_note_iterator **out, + git_commit *notes_commit); + +/** + * Frees an git_note_iterator + * + * @param it pointer to the iterator + */ +GIT_EXTERN(void) git_note_iterator_free(git_note_iterator *it); + +/** + * Return the current item (note_id and annotated_id) and advance the iterator + * internally to the next value + * + * @param note_id id of blob containing the message + * @param annotated_id id of the git object being annotated + * @param it pointer to the iterator + * + * @return 0 (no error), GIT_ITEROVER (iteration is done) or an error code + * (negative value) + */ +GIT_EXTERN(int) git_note_next( + git_oid *note_id, + git_oid *annotated_id, + git_note_iterator *it); + + +/** + * Read the note for an object + * + * The note must be freed manually by the user. + * + * @param out pointer to the read note; NULL in case of error + * @param repo repository where to look up the note + * @param notes_ref canonical name of the reference to use (optional); defaults to + * "refs/notes/commits" + * @param oid OID of the git object to read the note from + * + * @return 0 or an error code + */ +GIT_EXTERN(int) git_note_read( + git_note **out, + git_repository *repo, + const char *notes_ref, + const git_oid *oid); + + +/** + * Read the note for an object from a note commit + * + * The note must be freed manually by the user. + * + * @param out pointer to the read note; NULL in case of error + * @param repo repository where to look up the note + * @param notes_commit a pointer to the notes commit object + * @param oid OID of the git object to read the note from + * + * @return 0 or an error code + */ +GIT_EXTERN(int) git_note_commit_read( + git_note **out, + git_repository *repo, + git_commit *notes_commit, + const git_oid *oid); + +/** + * Get the note author + * + * @param note the note + * @return the author + */ +GIT_EXTERN(const git_signature *) git_note_author(const git_note *note); + +/** + * Get the note committer + * + * @param note the note + * @return the committer + */ +GIT_EXTERN(const git_signature *) git_note_committer(const git_note *note); + + +/** + * Get the note message + * + * @param note the note + * @return the note message + */ +GIT_EXTERN(const char *) git_note_message(const git_note *note); + + +/** + * Get the note object's id + * + * @param note the note + * @return the note object's id + */ +GIT_EXTERN(const git_oid *) git_note_id(const git_note *note); + +/** + * Add a note for an object + * + * @param out pointer to store the OID (optional); NULL in case of error + * @param repo repository where to store the note + * @param notes_ref canonical name of the reference to use (optional); + * defaults to "refs/notes/commits" + * @param author signature of the notes commit author + * @param committer signature of the notes commit committer + * @param oid OID of the git object to decorate + * @param note Content of the note to add for object oid + * @param force Overwrite existing note + * + * @return 0 or an error code + */ +GIT_EXTERN(int) git_note_create( + git_oid *out, + git_repository *repo, + const char *notes_ref, + const git_signature *author, + const git_signature *committer, + const git_oid *oid, + const char *note, + int force); + +/** + * Add a note for an object from a commit + * + * This function will create a notes commit for a given object, + * the commit is a dangling commit, no reference is created. + * + * @param notes_commit_out pointer to store the commit (optional); + * NULL in case of error + * @param notes_blob_out a point to the id of a note blob (optional) + * @param repo repository where the note will live + * @param parent Pointer to parent note + * or NULL if this shall start a new notes tree + * @param author signature of the notes commit author + * @param committer signature of the notes commit committer + * @param oid OID of the git object to decorate + * @param note Content of the note to add for object oid + * @param allow_note_overwrite Overwrite existing note + * + * @return 0 or an error code + */ +GIT_EXTERN(int) git_note_commit_create( + git_oid *notes_commit_out, + git_oid *notes_blob_out, + git_repository *repo, + git_commit *parent, + const git_signature *author, + const git_signature *committer, + const git_oid *oid, + const char *note, + int allow_note_overwrite); + +/** + * Remove the note for an object + * + * @param repo repository where the note lives + * @param notes_ref canonical name of the reference to use (optional); + * defaults to "refs/notes/commits" + * @param author signature of the notes commit author + * @param committer signature of the notes commit committer + * @param oid OID of the git object to remove the note from + * + * @return 0 or an error code + */ +GIT_EXTERN(int) git_note_remove( + git_repository *repo, + const char *notes_ref, + const git_signature *author, + const git_signature *committer, + const git_oid *oid); + +/** + * Remove the note for an object + * + * @param notes_commit_out pointer to store the new notes commit (optional); + * NULL in case of error. + * When removing a note a new tree containing all notes + * sans the note to be removed is created and a new commit + * pointing to that tree is also created. + * In the case where the resulting tree is an empty tree + * a new commit pointing to this empty tree will be returned. + * @param repo repository where the note lives + * @param notes_commit a pointer to the notes commit object + * @param author signature of the notes commit author + * @param committer signature of the notes commit committer + * @param oid OID of the git object to remove the note from + * + * @return 0 or an error code + */ +GIT_EXTERN(int) git_note_commit_remove( + git_oid *notes_commit_out, + git_repository *repo, + git_commit *notes_commit, + const git_signature *author, + const git_signature *committer, + const git_oid *oid); + +/** + * Free a git_note object + * + * @param note git_note object + */ +GIT_EXTERN(void) git_note_free(git_note *note); + +/** + * Get the default notes reference for a repository + * + * @param out buffer in which to store the name of the default notes reference + * @param repo The Git repository + * + * @return 0 or an error code + */ +GIT_EXTERN(int) git_note_default_ref(git_buf *out, git_repository *repo); + +/** + * Loop over all the notes within a specified namespace + * and issue a callback for each one. + * + * @param repo Repository where to find the notes. + * + * @param notes_ref Reference to read from (optional); defaults to + * "refs/notes/commits". + * + * @param note_cb Callback to invoke per found annotation. Return non-zero + * to stop looping. + * + * @param payload Extra parameter to callback function. + * + * @return 0 on success, non-zero callback return value, or error code + */ +GIT_EXTERN(int) git_note_foreach( + git_repository *repo, + const char *notes_ref, + git_note_foreach_cb note_cb, + void *payload); + +/** @} */ +GIT_END_DECL +#endif |