1 /* 2 * Copyright (C) the libgit2 contributors. All rights reserved. 3 * 4 * This file is part of libgit2, distributed under the GNU GPL v2 with 5 * a Linking Exception. For full terms see the included COPYING file. 6 */ 7 #ifndef INCLUDE_git_note_h__ 8 #define INCLUDE_git_note_h__ 9 10 #include "oid.h" 11 12 /** 13 * @file git2/notes.h 14 * @brief Git notes management routines 15 * @defgroup git_note Git notes management routines 16 * @ingroup Git 17 * @{ 18 */ 19 GIT_BEGIN_DECL 20 21 /** 22 * Callback for git_note_foreach. 23 * 24 * Receives: 25 * - blob_id: Oid of the blob containing the message 26 * - annotated_object_id: Oid of the git object being annotated 27 * - payload: Payload data passed to `git_note_foreach` 28 */ 29 typedef int GIT_CALLBACK(git_note_foreach_cb)( 30 const git_oid *blob_id, const git_oid *annotated_object_id, void *payload); 31 32 /** 33 * note iterator 34 */ 35 typedef struct git_iterator git_note_iterator; 36 37 /** 38 * Creates a new iterator for notes 39 * 40 * The iterator must be freed manually by the user. 41 * 42 * @param out pointer to the iterator 43 * @param repo repository where to look up the note 44 * @param notes_ref canonical name of the reference to use (optional); defaults to 45 * "refs/notes/commits" 46 * 47 * @return 0 or an error code 48 */ 49 GIT_EXTERN(int) git_note_iterator_new( 50 git_note_iterator **out, 51 git_repository *repo, 52 const char *notes_ref); 53 54 /** 55 * Creates a new iterator for notes from a commit 56 * 57 * The iterator must be freed manually by the user. 58 * 59 * @param out pointer to the iterator 60 * @param notes_commit a pointer to the notes commit object 61 * 62 * @return 0 or an error code 63 */ 64 GIT_EXTERN(int) git_note_commit_iterator_new( 65 git_note_iterator **out, 66 git_commit *notes_commit); 67 68 /** 69 * Frees an git_note_iterator 70 * 71 * @param it pointer to the iterator 72 */ 73 GIT_EXTERN(void) git_note_iterator_free(git_note_iterator *it); 74 75 /** 76 * Return the current item (note_id and annotated_id) and advance the iterator 77 * internally to the next value 78 * 79 * @param note_id id of blob containing the message 80 * @param annotated_id id of the git object being annotated 81 * @param it pointer to the iterator 82 * 83 * @return 0 (no error), GIT_ITEROVER (iteration is done) or an error code 84 * (negative value) 85 */ 86 GIT_EXTERN(int) git_note_next( 87 git_oid* note_id, 88 git_oid* annotated_id, 89 git_note_iterator *it); 90 91 92 /** 93 * Read the note for an object 94 * 95 * The note must be freed manually by the user. 96 * 97 * @param out pointer to the read note; NULL in case of error 98 * @param repo repository where to look up the note 99 * @param notes_ref canonical name of the reference to use (optional); defaults to 100 * "refs/notes/commits" 101 * @param oid OID of the git object to read the note from 102 * 103 * @return 0 or an error code 104 */ 105 GIT_EXTERN(int) git_note_read( 106 git_note **out, 107 git_repository *repo, 108 const char *notes_ref, 109 const git_oid *oid); 110 111 112 /** 113 * Read the note for an object from a note commit 114 * 115 * The note must be freed manually by the user. 116 * 117 * @param out pointer to the read note; NULL in case of error 118 * @param repo repository where to look up the note 119 * @param notes_commit a pointer to the notes commit object 120 * @param oid OID of the git object to read the note from 121 * 122 * @return 0 or an error code 123 */ 124 GIT_EXTERN(int) git_note_commit_read( 125 git_note **out, 126 git_repository *repo, 127 git_commit *notes_commit, 128 const git_oid *oid); 129 130 /** 131 * Get the note author 132 * 133 * @param note the note 134 * @return the author 135 */ 136 GIT_EXTERN(const git_signature *) git_note_author(const git_note *note); 137 138 /** 139 * Get the note committer 140 * 141 * @param note the note 142 * @return the committer 143 */ 144 GIT_EXTERN(const git_signature *) git_note_committer(const git_note *note); 145 146 147 /** 148 * Get the note message 149 * 150 * @param note the note 151 * @return the note message 152 */ 153 GIT_EXTERN(const char *) git_note_message(const git_note *note); 154 155 156 /** 157 * Get the note object's id 158 * 159 * @param note the note 160 * @return the note object's id 161 */ 162 GIT_EXTERN(const git_oid *) git_note_id(const git_note *note); 163 164 /** 165 * Add a note for an object 166 * 167 * @param out pointer to store the OID (optional); NULL in case of error 168 * @param repo repository where to store the note 169 * @param notes_ref canonical name of the reference to use (optional); 170 * defaults to "refs/notes/commits" 171 * @param author signature of the notes commit author 172 * @param committer signature of the notes commit committer 173 * @param oid OID of the git object to decorate 174 * @param note Content of the note to add for object oid 175 * @param force Overwrite existing note 176 * 177 * @return 0 or an error code 178 */ 179 GIT_EXTERN(int) git_note_create( 180 git_oid *out, 181 git_repository *repo, 182 const char *notes_ref, 183 const git_signature *author, 184 const git_signature *committer, 185 const git_oid *oid, 186 const char *note, 187 int force); 188 189 /** 190 * Add a note for an object from a commit 191 * 192 * This function will create a notes commit for a given object, 193 * the commit is a dangling commit, no reference is created. 194 * 195 * @param notes_commit_out pointer to store the commit (optional); 196 * NULL in case of error 197 * @param notes_blob_out a point to the id of a note blob (optional) 198 * @param repo repository where the note will live 199 * @param parent Pointer to parent note 200 * or NULL if this shall start a new notes tree 201 * @param author signature of the notes commit author 202 * @param committer signature of the notes commit committer 203 * @param oid OID of the git object to decorate 204 * @param note Content of the note to add for object oid 205 * @param allow_note_overwrite Overwrite existing note 206 * 207 * @return 0 or an error code 208 */ 209 GIT_EXTERN(int) git_note_commit_create( 210 git_oid *notes_commit_out, 211 git_oid *notes_blob_out, 212 git_repository *repo, 213 git_commit *parent, 214 const git_signature *author, 215 const git_signature *committer, 216 const git_oid *oid, 217 const char *note, 218 int allow_note_overwrite); 219 220 /** 221 * Remove the note for an object 222 * 223 * @param repo repository where the note lives 224 * @param notes_ref canonical name of the reference to use (optional); 225 * defaults to "refs/notes/commits" 226 * @param author signature of the notes commit author 227 * @param committer signature of the notes commit committer 228 * @param oid OID of the git object to remove the note from 229 * 230 * @return 0 or an error code 231 */ 232 GIT_EXTERN(int) git_note_remove( 233 git_repository *repo, 234 const char *notes_ref, 235 const git_signature *author, 236 const git_signature *committer, 237 const git_oid *oid); 238 239 /** 240 * Remove the note for an object 241 * 242 * @param notes_commit_out pointer to store the new notes commit (optional); 243 * NULL in case of error. 244 * When removing a note a new tree containing all notes 245 * sans the note to be removed is created and a new commit 246 * pointing to that tree is also created. 247 * In the case where the resulting tree is an empty tree 248 * a new commit pointing to this empty tree will be returned. 249 * @param repo repository where the note lives 250 * @param notes_commit a pointer to the notes commit object 251 * @param author signature of the notes commit author 252 * @param committer signature of the notes commit committer 253 * @param oid OID of the git object to remove the note from 254 * 255 * @return 0 or an error code 256 */ 257 GIT_EXTERN(int) git_note_commit_remove( 258 git_oid *notes_commit_out, 259 git_repository *repo, 260 git_commit *notes_commit, 261 const git_signature *author, 262 const git_signature *committer, 263 const git_oid *oid); 264 265 /** 266 * Free a git_note object 267 * 268 * @param note git_note object 269 */ 270 GIT_EXTERN(void) git_note_free(git_note *note); 271 272 /** 273 * Get the default notes reference for a repository 274 * 275 * @param out buffer in which to store the name of the default notes reference 276 * @param repo The Git repository 277 * 278 * @return 0 or an error code 279 */ 280 GIT_EXTERN(int) git_note_default_ref(git_buf *out, git_repository *repo); 281 282 /** 283 * Loop over all the notes within a specified namespace 284 * and issue a callback for each one. 285 * 286 * @param repo Repository where to find the notes. 287 * 288 * @param notes_ref Reference to read from (optional); defaults to 289 * "refs/notes/commits". 290 * 291 * @param note_cb Callback to invoke per found annotation. Return non-zero 292 * to stop looping. 293 * 294 * @param payload Extra parameter to callback function. 295 * 296 * @return 0 on success, non-zero callback return value, or error code 297 */ 298 GIT_EXTERN(int) git_note_foreach( 299 git_repository *repo, 300 const char *notes_ref, 301 git_note_foreach_cb note_cb, 302 void *payload); 303 304 /** @} */ 305 GIT_END_DECL 306 #endif 307