include/git2/notes.h

0001 /*
0002  * Copyright (C) the libgit2 contributors. All rights reserved.
0003  *
0004  * This file is part of libgit2, distributed under the GNU GPL v2 with
0005  * a Linking Exception. For full terms see the included COPYING file.
0006  */
0007 #ifndef INCLUDE_git_note_h__
0008 #define INCLUDE_git_note_h__
0009
0010 #include "oid.h"
0011
0012 /**
0013  * @file git2/notes.h
0014  * @brief Git notes management routines
0015  * @defgroup git_note Git notes management routines
0016  * @ingroup Git
0017  * @{
0018  */
0019 GIT_BEGIN_DECL
0020
0021 /**
0022  * Callback for git_note_foreach.
0023  *
0024  * Receives:
0025  * - blob_id: Oid of the blob containing the message
0026  * - annotated_object_id: Oid of the git object being annotated
0027  * - payload: Payload data passed to `git_note_foreach`
0028  */
0029 typedef int GIT_CALLBACK(git_note_foreach_cb)(
0030     const git_oid *blob_id, const git_oid *annotated_object_id, void *payload);
0031
0032 /**
0033  * note iterator
0034  */
0035 typedef struct git_iterator git_note_iterator;
0036
0037 /**
0038  * Creates a new iterator for notes
0039  *
0040  * The iterator must be freed manually by the user.
0041  *
0042  * @param out pointer to the iterator
0043  * @param repo repository where to look up the note
0044  * @param notes_ref canonical name of the reference to use (optional); defaults to
0045  *                  "refs/notes/commits"
0046  *
0047  * @return 0 or an error code
0048  */
0049 GIT_EXTERN(int) git_note_iterator_new(
0050     git_note_iterator **out,
0051     git_repository *repo,
0052     const char *notes_ref);
0053
0054 /**
0055  * Creates a new iterator for notes from a commit
0056  *
0057  * The iterator must be freed manually by the user.
0058  *
0059  * @param out pointer to the iterator
0060  * @param notes_commit a pointer to the notes commit object
0061  *
0062  * @return 0 or an error code
0063  */
0064 GIT_EXTERN(int) git_note_commit_iterator_new(
0065     git_note_iterator **out,
0066     git_commit *notes_commit);
0067
0068 /**
0069  * Frees an git_note_iterator
0070  *
0071  * @param it pointer to the iterator
0072  */
0073 GIT_EXTERN(void) git_note_iterator_free(git_note_iterator *it);
0074
0075 /**
0076  * Return the current item (note_id and annotated_id) and advance the iterator
0077  * internally to the next value
0078  *
0079  * @param note_id id of blob containing the message
0080  * @param annotated_id id of the git object being annotated
0081  * @param it pointer to the iterator
0082  *
0083  * @return 0 (no error), GIT_ITEROVER (iteration is done) or an error code
0084  *         (negative value)
0085  */
0086 GIT_EXTERN(int) git_note_next(
0087     git_oid *note_id,
0088     git_oid *annotated_id,
0089     git_note_iterator *it);
0090
0091
0092 /**
0093  * Read the note for an object
0094  *
0095  * The note must be freed manually by the user.
0096  *
0097  * @param out pointer to the read note; NULL in case of error
0098  * @param repo repository where to look up the note
0099  * @param notes_ref canonical name of the reference to use (optional); defaults to
0100  *                  "refs/notes/commits"
0101  * @param oid OID of the git object to read the note from
0102  *
0103  * @return 0 or an error code
0104  */
0105 GIT_EXTERN(int) git_note_read(
0106     git_note **out,
0107     git_repository *repo,
0108     const char *notes_ref,
0109     const git_oid *oid);
0110
0111
0112 /**
0113  * Read the note for an object from a note commit
0114  *
0115  * The note must be freed manually by the user.
0116  *
0117  * @param out pointer to the read note; NULL in case of error
0118  * @param repo repository where to look up the note
0119  * @param notes_commit a pointer to the notes commit object
0120  * @param oid OID of the git object to read the note from
0121  *
0122  * @return 0 or an error code
0123  */
0124 GIT_EXTERN(int) git_note_commit_read(
0125     git_note **out,
0126     git_repository *repo,
0127     git_commit *notes_commit,
0128     const git_oid *oid);
0129
0130 /**
0131  * Get the note author
0132  *
0133  * @param note the note
0134  * @return the author
0135  */
0136 GIT_EXTERN(const git_signature *) git_note_author(const git_note *note);
0137
0138 /**
0139  * Get the note committer
0140  *
0141  * @param note the note
0142  * @return the committer
0143  */
0144 GIT_EXTERN(const git_signature *) git_note_committer(const git_note *note);
0145
0146
0147 /**
0148  * Get the note message
0149  *
0150  * @param note the note
0151  * @return the note message
0152  */
0153 GIT_EXTERN(const char *) git_note_message(const git_note *note);
0154
0155
0156 /**
0157  * Get the note object's id
0158  *
0159  * @param note the note
0160  * @return the note object's id
0161  */
0162 GIT_EXTERN(const git_oid *) git_note_id(const git_note *note);
0163
0164 /**
0165  * Add a note for an object
0166  *
0167  * @param out pointer to store the OID (optional); NULL in case of error
0168  * @param repo repository where to store the note
0169  * @param notes_ref canonical name of the reference to use (optional);
0170  *                  defaults to "refs/notes/commits"
0171  * @param author signature of the notes commit author
0172  * @param committer signature of the notes commit committer
0173  * @param oid OID of the git object to decorate
0174  * @param note Content of the note to add for object oid
0175  * @param force Overwrite existing note
0176  *
0177  * @return 0 or an error code
0178  */
0179 GIT_EXTERN(int) git_note_create(
0180     git_oid *out,
0181     git_repository *repo,
0182     const char *notes_ref,
0183     const git_signature *author,
0184     const git_signature *committer,
0185     const git_oid *oid,
0186     const char *note,
0187     int force);
0188
0189 /**
0190  * Add a note for an object from a commit
0191  *
0192  * This function will create a notes commit for a given object,
0193  * the commit is a dangling commit, no reference is created.
0194  *
0195  * @param notes_commit_out pointer to store the commit (optional);
0196  *                  NULL in case of error
0197  * @param notes_blob_out a point to the id of a note blob (optional)
0198  * @param repo repository where the note will live
0199  * @param parent Pointer to parent note
0200  *                  or NULL if this shall start a new notes tree
0201  * @param author signature of the notes commit author
0202  * @param committer signature of the notes commit committer
0203  * @param oid OID of the git object to decorate
0204  * @param note Content of the note to add for object oid
0205  * @param allow_note_overwrite Overwrite existing note
0206  *
0207  * @return 0 or an error code
0208  */
0209 GIT_EXTERN(int) git_note_commit_create(
0210     git_oid *notes_commit_out,
0211     git_oid *notes_blob_out,
0212     git_repository *repo,
0213     git_commit *parent,
0214     const git_signature *author,
0215     const git_signature *committer,
0216     const git_oid *oid,
0217     const char *note,
0218     int allow_note_overwrite);
0219
0220 /**
0221  * Remove the note for an object
0222  *
0223  * @param repo repository where the note lives
0224  * @param notes_ref canonical name of the reference to use (optional);
0225  *                  defaults to "refs/notes/commits"
0226  * @param author signature of the notes commit author
0227  * @param committer signature of the notes commit committer
0228  * @param oid OID of the git object to remove the note from
0229  *
0230  * @return 0 or an error code
0231  */
0232 GIT_EXTERN(int) git_note_remove(
0233     git_repository *repo,
0234     const char *notes_ref,
0235     const git_signature *author,
0236     const git_signature *committer,
0237     const git_oid *oid);
0238
0239 /**
0240  * Remove the note for an object
0241  *
0242  * @param notes_commit_out pointer to store the new notes commit (optional);
0243  *                  NULL in case of error.
0244  *                  When removing a note a new tree containing all notes
0245  *                  sans the note to be removed is created and a new commit
0246  *                  pointing to that tree is also created.
0247  *                  In the case where the resulting tree is an empty tree
0248  *                  a new commit pointing to this empty tree will be returned.
0249  * @param repo repository where the note lives
0250  * @param notes_commit a pointer to the notes commit object
0251  * @param author signature of the notes commit author
0252  * @param committer signature of the notes commit committer
0253  * @param oid OID of the git object to remove the note from
0254  *
0255  * @return 0 or an error code
0256  */
0257 GIT_EXTERN(int) git_note_commit_remove(
0258         git_oid *notes_commit_out,
0259         git_repository *repo,
0260         git_commit *notes_commit,
0261         const git_signature *author,
0262         const git_signature *committer,
0263         const git_oid *oid);
0264
0265 /**
0266  * Free a git_note object
0267  *
0268  * @param note git_note object
0269  */
0270 GIT_EXTERN(void) git_note_free(git_note *note);
0271
0272 /**
0273  * Get the default notes reference for a repository
0274  *
0275  * @param out buffer in which to store the name of the default notes reference
0276  * @param repo The Git repository
0277  *
0278  * @return 0 or an error code
0279  */
0280 GIT_EXTERN(int) git_note_default_ref(git_buf *out, git_repository *repo);
0281
0282 /**
0283  * Loop over all the notes within a specified namespace
0284  * and issue a callback for each one.
0285  *
0286  * @param repo Repository where to find the notes.
0287  *
0288  * @param notes_ref Reference to read from (optional); defaults to
0289  *        "refs/notes/commits".
0290  *
0291  * @param note_cb Callback to invoke per found annotation.  Return non-zero
0292  *        to stop looping.
0293  *
0294  * @param payload Extra parameter to callback function.
0295  *
0296  * @return 0 on success, non-zero callback return value, or error code
0297  */
0298 GIT_EXTERN(int) git_note_foreach(
0299     git_repository *repo,
0300     const char *notes_ref,
0301     git_note_foreach_cb note_cb,
0302     void *payload);
0303
0304 /** @} */
0305 GIT_END_DECL
0306 #endif