]>
Commit | Line | Data |
---|---|---|
bf477ed4 MS |
1 | /* |
2 | * Copyright (C) 2009-2012 the libgit2 contributors | |
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 | |
bf477ed4 MS |
32 | /** |
33 | * Read the note for an object | |
34 | * | |
35 | * The note must be freed manually by the user. | |
36 | * | |
de5596bf | 37 | * @param out pointer to the read note; NULL in case of error |
5fd17fc2 | 38 | * @param repo repository where to look up the note |
de5596bf BS |
39 | * @param notes_ref canonical name of the reference to use (optional); defaults to |
40 | * "refs/notes/commits" | |
5fd17fc2 | 41 | * @param oid OID of the git object to read the note from |
bf477ed4 | 42 | * |
e172cf08 | 43 | * @return 0 or an error code |
bf477ed4 | 44 | */ |
de5596bf BS |
45 | GIT_EXTERN(int) git_note_read( |
46 | git_note **out, | |
47 | git_repository *repo, | |
48 | const char *notes_ref, | |
49 | const git_oid *oid); | |
bf477ed4 MS |
50 | |
51 | /** | |
52 | * Get the note message | |
53 | * | |
54 | * @param note | |
55 | * @return the note message | |
56 | */ | |
de5596bf | 57 | GIT_EXTERN(const char *) git_note_message(const git_note *note); |
bf477ed4 MS |
58 | |
59 | ||
60 | /** | |
61 | * Get the note object OID | |
62 | * | |
63 | * @param note | |
64 | * @return the note object OID | |
65 | */ | |
de5596bf | 66 | GIT_EXTERN(const git_oid *) git_note_oid(const git_note *note); |
bf477ed4 | 67 | |
bf477ed4 MS |
68 | /** |
69 | * Add a note for an object | |
70 | * | |
22408f4d | 71 | * @param out pointer to store the OID (optional); NULL in case of error |
5fd17fc2 | 72 | * @param repo repository where to store the note |
bf477ed4 MS |
73 | * @param author signature of the notes commit author |
74 | * @param committer signature of the notes commit committer | |
5fd17fc2 | 75 | * @param notes_ref canonical name of the reference to use (optional); |
76 | * defaults to "refs/notes/commits" | |
77 | * @param oid OID of the git object to decorate | |
78 | * @param note Content of the note to add for object oid | |
bf477ed4 | 79 | * |
e172cf08 | 80 | * @return 0 or an error code |
bf477ed4 | 81 | */ |
de5596bf BS |
82 | GIT_EXTERN(int) git_note_create( |
83 | git_oid *out, | |
84 | git_repository *repo, | |
85 | const git_signature *author, | |
86 | const git_signature *committer, | |
87 | const char *notes_ref, | |
88 | const git_oid *oid, | |
89 | const char *note); | |
bf477ed4 MS |
90 | |
91 | ||
92 | /** | |
93 | * Remove the note for an object | |
94 | * | |
5fd17fc2 | 95 | * @param repo repository where the note lives |
96 | * @param notes_ref canonical name of the reference to use (optional); | |
97 | * defaults to "refs/notes/commits" | |
bf477ed4 MS |
98 | * @param author signature of the notes commit author |
99 | * @param committer signature of the notes commit committer | |
5fd17fc2 | 100 | * @param oid OID of the git object to remove the note from |
bf477ed4 | 101 | * |
e172cf08 | 102 | * @return 0 or an error code |
bf477ed4 | 103 | */ |
de5596bf BS |
104 | GIT_EXTERN(int) git_note_remove( |
105 | git_repository *repo, | |
106 | const char *notes_ref, | |
107 | const git_signature *author, | |
108 | const git_signature *committer, | |
109 | const git_oid *oid); | |
bf477ed4 MS |
110 | |
111 | /** | |
112 | * Free a git_note object | |
113 | * | |
114 | * @param note git_note object | |
115 | */ | |
116 | GIT_EXTERN(void) git_note_free(git_note *note); | |
117 | ||
630c5a4a MS |
118 | /** |
119 | * Get the default notes reference for a repository | |
120 | * | |
121 | * @param out Pointer to the default notes reference | |
122 | * @param repo The Git repository | |
123 | * | |
e172cf08 | 124 | * @return 0 or an error code |
630c5a4a MS |
125 | */ |
126 | GIT_EXTERN(int) git_note_default_ref(const char **out, git_repository *repo); | |
127 | ||
86ecd844 | 128 | /** |
129 | * Loop over all the notes within a specified namespace | |
130 | * and issue a callback for each one. | |
131 | * | |
132 | * @param repo Repository where to find the notes. | |
133 | * | |
d45ada03 | 134 | * @param notes_ref Reference to read from (optional); defaults to |
5dca2010 | 135 | * "refs/notes/commits". |
86ecd844 | 136 | * |
5dca2010 RB |
137 | * @param note_cb Callback to invoke per found annotation. Return non-zero |
138 | * to stop looping. | |
86ecd844 | 139 | * |
140 | * @param payload Extra parameter to callback function. | |
141 | * | |
5dca2010 | 142 | * @return 0 on success, GIT_EUSER on non-zero callback, or error code |
86ecd844 | 143 | */ |
144 | GIT_EXTERN(int) git_note_foreach( | |
5dca2010 RB |
145 | git_repository *repo, |
146 | const char *notes_ref, | |
de5596bf | 147 | git_note_foreach_cb note_cb, |
2bd5998c | 148 | void *payload); |
86ecd844 | 149 | |
bf477ed4 MS |
150 | /** @} */ |
151 | GIT_END_DECL | |
152 | #endif |