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 * @param out_ pointer to the iterator 47 * @param repo repository where to look up the note 48 * @param notes_ref canonical name of the reference to use (optional); defaults 49 * to "refs/notes/commits" 50 * 51 * @return 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 * @param out_ pointer to the iterator 62 * @param notes_commit a pointer to the notes commit object 63 * 64 * @return 0 or an error code 65 */ 66 //GIT_EXTERN 67 int git_note_commit_iterator_new(.git_note_iterator** out_, libgit2_d.types.git_commit* notes_commit); 68 69 /** 70 * Frees an git_note_iterator 71 * 72 * @param it pointer to the iterator 73 */ 74 //GIT_EXTERN 75 void git_note_iterator_free(.git_note_iterator* it); 76 77 /** 78 * Return the current item (note_id and annotated_id) and advance the iterator 79 * internally to the next value 80 * 81 * @param note_id id of blob containing the message 82 * @param annotated_id id of the git object being annotated 83 * @param it pointer to the iterator 84 * 85 * @return 0 (no error), git_error_code.GIT_ITEROVER (iteration is done) or an error code 86 * (negative value) 87 */ 88 //GIT_EXTERN 89 int git_note_next(libgit2_d.oid.git_oid* note_id, libgit2_d.oid.git_oid* annotated_id, .git_note_iterator* it); 90 91 /** 92 * Read the note for an object 93 * 94 * The note must be freed manually by the user. 95 * 96 * @param out_ pointer to the read note; null in case of error 97 * @param repo repository where to look up the note 98 * @param notes_ref canonical name of the reference to use (optional); defaults 99 * to "refs/notes/commits" 100 * @param oid OID of the git object to read the note from 101 * 102 * @return 0 or an error code 103 */ 104 //GIT_EXTERN 105 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); 106 107 /** 108 * Read the note for an object from a note commit 109 * 110 * The note must be freed manually by the user. 111 * 112 * @param out_ pointer to the read note; null in case of error 113 * @param repo repository where to look up the note 114 * @param notes_commit a pointer to the notes commit object 115 * @param oid OID of the git object to read the note from 116 * 117 * @return 0 or an error code 118 */ 119 //GIT_EXTERN 120 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); 121 122 /** 123 * Get the note author 124 * 125 * @param note the note 126 * @return the author 127 */ 128 //GIT_EXTERN 129 const (libgit2_d.types.git_signature)* git_note_author(const (libgit2_d.types.git_note)* note); 130 131 /** 132 * Get the note committer 133 * 134 * @param note the note 135 * @return the committer 136 */ 137 //GIT_EXTERN 138 const (libgit2_d.types.git_signature)* git_note_committer(const (libgit2_d.types.git_note)* note); 139 140 /** 141 * Get the note message 142 * 143 * @param note the note 144 * @return the note message 145 */ 146 //GIT_EXTERN 147 const (char)* git_note_message(const (libgit2_d.types.git_note)* note); 148 149 /** 150 * Get the note object's id 151 * 152 * @param note the note 153 * @return the note object's id 154 */ 155 //GIT_EXTERN 156 const (libgit2_d.oid.git_oid)* git_note_id(const (libgit2_d.types.git_note)* note); 157 158 /** 159 * Add a note for an object 160 * 161 * @param out_ pointer to store the OID (optional); null in case of error 162 * @param repo repository where to store the note 163 * @param notes_ref canonical name of the reference to use (optional); 164 * defaults to "refs/notes/commits" 165 * @param author signature of the notes commit author 166 * @param committer signature of the notes commit committer 167 * @param oid OID of the git object to decorate 168 * @param note Content of the note to add for object oid 169 * @param force Overwrite existing note 170 * 171 * @return 0 or an error code 172 */ 173 //GIT_EXTERN 174 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); 175 176 /** 177 * Add a note for an object from a commit 178 * 179 * This function will create a notes commit for a given object, 180 * the commit is a dangling commit, no reference is created. 181 * 182 * @param notes_commit_out pointer to store the commit (optional); 183 * null in case of error 184 * @param notes_blob_out a point to the id of a note blob (optional) 185 * @param repo repository where the note will live 186 * @param parent Pointer to parent note 187 * or null if this shall start a new notes 188 *tree 189 * @param author signature of the notes commit author 190 * @param committer signature of the notes commit committer 191 * @param oid OID of the git object to decorate 192 * @param note Content of the note to add for object oid 193 * @param allow_note_overwrite Overwrite existing note 194 * 195 * @return 0 or an error code 196 */ 197 //GIT_EXTERN 198 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); 199 200 /** 201 * Remove the note for an object 202 * 203 * @param repo repository where the note lives 204 * @param notes_ref canonical name of the reference to use (optional); 205 * defaults to "refs/notes/commits" 206 * @param author signature of the notes commit author 207 * @param committer signature of the notes commit committer 208 * @param oid OID of the git object to remove the note from 209 * 210 * @return 0 or an error code 211 */ 212 //GIT_EXTERN 213 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); 214 215 /** 216 * Remove the note for an object 217 * 218 * @param notes_commit_out pointer to store the new notes commit (optional); 219 * null in case of error. 220 * When removing a note a new tree containing all 221 *notes sans the note to be removed is created and a new commit pointing to that 222 *tree is also created. In the case where the resulting tree is an empty tree a 223 *new commit pointing to this empty tree will be returned. 224 * @param repo repository where the note lives 225 * @param notes_commit a pointer to the notes commit object 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 233 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); 234 235 /** 236 * Free a git_note object 237 * 238 * @param note git_note object 239 */ 240 //GIT_EXTERN 241 void git_note_free(libgit2_d.types.git_note* note); 242 243 /** 244 * Get the default notes reference for a repository 245 * 246 * @param out_ buffer in which to store the name of the default notes reference 247 * @param repo The Git repository 248 * 249 * @return 0 or an error code 250 */ 251 //GIT_EXTERN 252 int git_note_default_ref(libgit2_d.buffer.git_buf* out_, libgit2_d.types.git_repository* repo); 253 254 /** 255 * Loop over all the notes within a specified namespace 256 * and issue a callback for each one. 257 * 258 * @param repo Repository where to find the notes. 259 * 260 * @param notes_ref Reference to read from (optional); defaults to 261 * "refs/notes/commits". 262 * 263 * @param note_cb Callback to invoke per found annotation. Return non-zero 264 * to stop looping. 265 * 266 * @param payload Extra parameter to callback function. 267 * 268 * @return 0 on success, non-zero callback return value, or error code 269 */ 270 //GIT_EXTERN 271 int git_note_foreach(libgit2_d.types.git_repository* repo, const (char)* notes_ref, .git_note_foreach_cb note_cb, void* payload); 272 273 /** @} */