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