]>
Commit | Line | Data |
---|---|---|
bf477ed4 | 1 | /* |
359fc2d2 | 2 | * Copyright (C) the libgit2 contributors. All rights reserved. |
bf477ed4 MS |
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 | ||
de5596bf BS |
21 | /** |
22 | * Callback for git_note_foreach. | |
2bd5998c RB |
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` | |
de5596bf | 28 | */ |
2bd5998c RB |
29 | typedef int (*git_note_foreach_cb)( |
30 | const git_oid *blob_id, const git_oid *annotated_object_id, void *payload); | |
de5596bf | 31 | |
6edb427b NG |
32 | /** |
33 | * note iterator | |
34 | */ | |
1a90dcf6 | 35 | typedef struct git_iterator git_note_iterator; |
6edb427b NG |
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( | |
1a90dcf6 | 50 | git_note_iterator **out, |
6edb427b NG |
51 | git_repository *repo, |
52 | const char *notes_ref); | |
53 | ||
1a90dcf6 NG |
54 | /** |
55 | * Frees an git_note_iterator | |
56 | * | |
57 | * @param it pointer to the iterator | |
58 | */ | |
59 | GIT_EXTERN(void) git_note_iterator_free(git_note_iterator *it); | |
60 | ||
6edb427b | 61 | /** |
f7b18502 NG |
62 | * Returns the current item (note_id and annotated_id) and advance the iterator |
63 | * internally to the next value | |
6edb427b NG |
64 | * |
65 | * The notes must not be freed manually by the user. | |
66 | * | |
67 | * @param it pointer to the iterator | |
68 | * @param note_id id of blob containing the message | |
69 | * @param annotated_id id of the git object being annotated | |
70 | * | |
f7b18502 NG |
71 | * @return 0 (no error), GIT_ITEROVER (iteration is done) or an error code |
72 | * (negative value) | |
6edb427b NG |
73 | */ |
74 | GIT_EXTERN(int) git_note_next( | |
75 | git_oid* note_id, | |
76 | git_oid* annotated_id, | |
1a90dcf6 | 77 | git_note_iterator *it); |
6edb427b NG |
78 | |
79 | ||
bf477ed4 MS |
80 | /** |
81 | * Read the note for an object | |
82 | * | |
83 | * The note must be freed manually by the user. | |
84 | * | |
de5596bf | 85 | * @param out pointer to the read note; NULL in case of error |
5fd17fc2 | 86 | * @param repo repository where to look up the note |
de5596bf BS |
87 | * @param notes_ref canonical name of the reference to use (optional); defaults to |
88 | * "refs/notes/commits" | |
5fd17fc2 | 89 | * @param oid OID of the git object to read the note from |
bf477ed4 | 90 | * |
e172cf08 | 91 | * @return 0 or an error code |
bf477ed4 | 92 | */ |
de5596bf BS |
93 | GIT_EXTERN(int) git_note_read( |
94 | git_note **out, | |
95 | git_repository *repo, | |
96 | const char *notes_ref, | |
97 | const git_oid *oid); | |
bf477ed4 MS |
98 | |
99 | /** | |
100 | * Get the note message | |
101 | * | |
c05a55b0 | 102 | * @param note the note |
bf477ed4 MS |
103 | * @return the note message |
104 | */ | |
de5596bf | 105 | GIT_EXTERN(const char *) git_note_message(const git_note *note); |
bf477ed4 MS |
106 | |
107 | ||
108 | /** | |
109 | * Get the note object OID | |
110 | * | |
c05a55b0 | 111 | * @param note the note |
bf477ed4 MS |
112 | * @return the note object OID |
113 | */ | |
de5596bf | 114 | GIT_EXTERN(const git_oid *) git_note_oid(const git_note *note); |
bf477ed4 | 115 | |
bf477ed4 MS |
116 | /** |
117 | * Add a note for an object | |
118 | * | |
22408f4d | 119 | * @param out pointer to store the OID (optional); NULL in case of error |
5fd17fc2 | 120 | * @param repo repository where to store the note |
bf477ed4 MS |
121 | * @param author signature of the notes commit author |
122 | * @param committer signature of the notes commit committer | |
5fd17fc2 | 123 | * @param notes_ref canonical name of the reference to use (optional); |
124 | * defaults to "refs/notes/commits" | |
125 | * @param oid OID of the git object to decorate | |
126 | * @param note Content of the note to add for object oid | |
8716b499 | 127 | * @param force Overwrite existing note |
bf477ed4 | 128 | * |
e172cf08 | 129 | * @return 0 or an error code |
bf477ed4 | 130 | */ |
de5596bf BS |
131 | GIT_EXTERN(int) git_note_create( |
132 | git_oid *out, | |
133 | git_repository *repo, | |
134 | const git_signature *author, | |
135 | const git_signature *committer, | |
136 | const char *notes_ref, | |
137 | const git_oid *oid, | |
8716b499 NV |
138 | const char *note, |
139 | int force); | |
bf477ed4 MS |
140 | |
141 | ||
142 | /** | |
143 | * Remove the note for an object | |
144 | * | |
5fd17fc2 | 145 | * @param repo repository where the note lives |
146 | * @param notes_ref canonical name of the reference to use (optional); | |
147 | * defaults to "refs/notes/commits" | |
bf477ed4 MS |
148 | * @param author signature of the notes commit author |
149 | * @param committer signature of the notes commit committer | |
5fd17fc2 | 150 | * @param oid OID of the git object to remove the note from |
bf477ed4 | 151 | * |
e172cf08 | 152 | * @return 0 or an error code |
bf477ed4 | 153 | */ |
de5596bf BS |
154 | GIT_EXTERN(int) git_note_remove( |
155 | git_repository *repo, | |
156 | const char *notes_ref, | |
157 | const git_signature *author, | |
158 | const git_signature *committer, | |
159 | const git_oid *oid); | |
bf477ed4 MS |
160 | |
161 | /** | |
162 | * Free a git_note object | |
163 | * | |
164 | * @param note git_note object | |
165 | */ | |
166 | GIT_EXTERN(void) git_note_free(git_note *note); | |
167 | ||
630c5a4a MS |
168 | /** |
169 | * Get the default notes reference for a repository | |
170 | * | |
171 | * @param out Pointer to the default notes reference | |
172 | * @param repo The Git repository | |
173 | * | |
e172cf08 | 174 | * @return 0 or an error code |
630c5a4a MS |
175 | */ |
176 | GIT_EXTERN(int) git_note_default_ref(const char **out, git_repository *repo); | |
177 | ||
86ecd844 | 178 | /** |
179 | * Loop over all the notes within a specified namespace | |
180 | * and issue a callback for each one. | |
181 | * | |
182 | * @param repo Repository where to find the notes. | |
183 | * | |
d45ada03 | 184 | * @param notes_ref Reference to read from (optional); defaults to |
5dca2010 | 185 | * "refs/notes/commits". |
86ecd844 | 186 | * |
5dca2010 RB |
187 | * @param note_cb Callback to invoke per found annotation. Return non-zero |
188 | * to stop looping. | |
86ecd844 | 189 | * |
190 | * @param payload Extra parameter to callback function. | |
191 | * | |
5dca2010 | 192 | * @return 0 on success, GIT_EUSER on non-zero callback, or error code |
86ecd844 | 193 | */ |
194 | GIT_EXTERN(int) git_note_foreach( | |
5dca2010 RB |
195 | git_repository *repo, |
196 | const char *notes_ref, | |
de5596bf | 197 | git_note_foreach_cb note_cb, |
2bd5998c | 198 | void *payload); |
86ecd844 | 199 | |
bf477ed4 MS |
200 | /** @} */ |
201 | GIT_END_DECL | |
202 | #endif |