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