| /* |
| * 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_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); |
| |
| /** |
| * 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); |
| |
| /** |
| * 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); |
| |
| |
| /** |
| * 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); |
| |
| /** |
| * 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 |