]>
Commit | Line | Data |
---|---|---|
2f8a8ab2 VM |
1 | /* |
2 | * This file is free software; you can redistribute it and/or modify | |
3 | * it under the terms of the GNU General Public License, version 2, | |
4 | * as published by the Free Software Foundation. | |
5 | * | |
6 | * In addition to the permissions in the GNU General Public License, | |
7 | * the authors give you unlimited permission to link the compiled | |
8 | * version of this file into combinations with other programs, | |
9 | * and to distribute those combinations without any restriction | |
10 | * coming from the use of this file. (The General Public License | |
11 | * restrictions do apply in other respects; for example, they cover | |
12 | * modification of the file, and distribution when not linked into | |
13 | * a combined executable.) | |
14 | * | |
15 | * This file is distributed in the hope that it will be useful, but | |
16 | * WITHOUT ANY WARRANTY; without even the implied warranty of | |
17 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
18 | * General Public License for more details. | |
19 | * | |
20 | * You should have received a copy of the GNU General Public License | |
21 | * along with this program; see the file COPYING. If not, write to | |
22 | * the Free Software Foundation, 51 Franklin Street, Fifth Floor, | |
23 | * Boston, MA 02110-1301, USA. | |
24 | */ | |
25 | #ifndef INCLUDE_git_refs_h__ | |
26 | #define INCLUDE_git_refs_h__ | |
27 | ||
28 | #include "common.h" | |
29 | #include "types.h" | |
fc70832a | 30 | #include "oid.h" |
2f8a8ab2 VM |
31 | |
32 | /** | |
33 | * @file git2/refs.h | |
34 | * @brief Git reference management routines | |
35 | * @defgroup git_reference Git reference management routines | |
36 | * @ingroup Git | |
37 | * @{ | |
38 | */ | |
39 | GIT_BEGIN_DECL | |
40 | ||
5de079b8 VM |
41 | /** |
42 | * Lookup a reference by its name in a repository. | |
43 | * | |
44 | * The generated reference is owned by the repository and | |
45 | * should not be freed by the user. | |
46 | * | |
47 | * @param reference_out pointer to the looked-up reference | |
48 | * @param repo the repository to look up the reference | |
49 | * @param name the long name for the reference (e.g. HEAD, ref/heads/master, refs/tags/v0.1.0, ...) | |
50 | * @return 0 on success; error code otherwise | |
51 | */ | |
52 | GIT_EXTERN(int) git_reference_lookup(git_reference **reference_out, git_repository *repo, const char *name); | |
53 | ||
2f8a8ab2 | 54 | /** |
1d8cc731 | 55 | * Create a new symbolic reference. |
2f8a8ab2 | 56 | * |
1d8cc731 | 57 | * The reference will be created in the repository and written |
58 | * to the disk. | |
2f8a8ab2 | 59 | * |
32054c24 VM |
60 | * This reference is owned by the repository and shall not |
61 | * be free'd by the user. | |
62 | * | |
d5afc039 VM |
63 | * If `force` is true and there already exists a reference |
64 | * with the same name, it will be overwritten. | |
fa204962 CMN |
65 | * |
66 | * @param ref_out Pointer to the newly created reference | |
67 | * @param repo Repository where that reference will live | |
68 | * @param name The name of the reference | |
69 | * @param target The target of the reference | |
d5afc039 | 70 | * @param force Overwrite existing references |
fa204962 CMN |
71 | * @return 0 on success; error code otherwise |
72 | */ | |
d5afc039 | 73 | GIT_EXTERN(int) git_reference_create_symbolic(git_reference **ref_out, git_repository *repo, const char *name, const char *target, int force); |
fa204962 | 74 | |
1d8cc731 | 75 | /** |
76 | * Create a new object id reference. | |
77 | * | |
78 | * The reference will be created in the repository and written | |
79 | * to the disk. | |
80 | * | |
32054c24 VM |
81 | * This reference is owned by the repository and shall not |
82 | * be free'd by the user. | |
83 | * | |
d5afc039 VM |
84 | * If `force` is true and there already exists a reference |
85 | * with the same name, it will be overwritten. | |
fa204962 CMN |
86 | * |
87 | * @param ref_out Pointer to the newly created reference | |
88 | * @param repo Repository where that reference will live | |
89 | * @param name The name of the reference | |
90 | * @param id The object id pointed to by the reference. | |
d5afc039 | 91 | * @param force Overwrite existing references |
fa204962 CMN |
92 | * @return 0 on success; error code otherwise |
93 | */ | |
d5afc039 | 94 | GIT_EXTERN(int) git_reference_create_oid(git_reference **ref_out, git_repository *repo, const char *name, const git_oid *id, int force); |
fa204962 | 95 | |
2f8a8ab2 VM |
96 | /** |
97 | * Get the OID pointed to by a reference. | |
98 | * | |
99 | * Only available if the reference is direct (i.e. not symbolic) | |
100 | * | |
101 | * @param ref The reference | |
102 | * @return a pointer to the oid if available, NULL otherwise | |
103 | */ | |
104 | GIT_EXTERN(const git_oid *) git_reference_oid(git_reference *ref); | |
105 | ||
106 | /** | |
107 | * Get full name to the reference pointed by this reference | |
108 | * | |
109 | * Only available if the reference is symbolic | |
110 | * | |
111 | * @param ref The reference | |
112 | * @return a pointer to the name if available, NULL otherwise | |
113 | */ | |
114 | GIT_EXTERN(const char *) git_reference_target(git_reference *ref); | |
115 | ||
116 | /** | |
117 | * Get the type of a reference | |
118 | * | |
119 | * Either direct (GIT_REF_OID) or symbolic (GIT_REF_SYMBOLIC) | |
120 | * | |
121 | * @param ref The reference | |
122 | * @return the type | |
123 | */ | |
124 | GIT_EXTERN(git_rtype) git_reference_type(git_reference *ref); | |
125 | ||
126 | /** | |
127 | * Get the full name of a reference | |
128 | * | |
129 | * @param ref The reference | |
130 | * @return the full name for the ref | |
131 | */ | |
132 | GIT_EXTERN(const char *) git_reference_name(git_reference *ref); | |
133 | ||
134 | /** | |
135 | * Resolve a symbolic reference | |
136 | * | |
137 | * Thie method iteratively peels a symbolic reference | |
138 | * until it resolves to a direct reference to an OID. | |
139 | * | |
140 | * If a direct reference is passed as an argument, | |
141 | * that reference is returned immediately | |
142 | * | |
143 | * @param resolved_ref Pointer to the peeled reference | |
144 | * @param ref The reference | |
145 | * @return 0 on success; error code otherwise | |
146 | */ | |
147 | GIT_EXTERN(int) git_reference_resolve(git_reference **resolved_ref, git_reference *ref); | |
148 | ||
2f8a8ab2 VM |
149 | /** |
150 | * Get the repository where a reference resides | |
151 | * | |
152 | * @param ref The reference | |
153 | * @return a pointer to the repo | |
154 | */ | |
155 | GIT_EXTERN(git_repository *) git_reference_owner(git_reference *ref); | |
156 | ||
2f8a8ab2 | 157 | /** |
32054c24 | 158 | * Set the symbolic target of a reference. |
2f8a8ab2 | 159 | * |
32054c24 VM |
160 | * The reference must be a symbolic reference, otherwise |
161 | * this method will fail. | |
2f8a8ab2 | 162 | * |
32054c24 VM |
163 | * The reference will be automatically updated in |
164 | * memory and on disk. | |
2f8a8ab2 VM |
165 | * |
166 | * @param ref The reference | |
167 | * @param target The new target for the reference | |
1d8cc731 | 168 | * @return 0 on success; error code otherwise |
2f8a8ab2 | 169 | */ |
1d8cc731 | 170 | GIT_EXTERN(int) git_reference_set_target(git_reference *ref, const char *target); |
2f8a8ab2 VM |
171 | |
172 | /** | |
173 | * Set the OID target of a reference. | |
174 | * | |
32054c24 VM |
175 | * The reference must be a direct reference, otherwise |
176 | * this method will fail. | |
2f8a8ab2 | 177 | * |
32054c24 VM |
178 | * The reference will be automatically updated in |
179 | * memory and on disk. | |
2f8a8ab2 VM |
180 | * |
181 | * @param ref The reference | |
d144c569 | 182 | * @param id The new target OID for the reference |
1d8cc731 | 183 | * @return 0 on success; error code otherwise |
2f8a8ab2 | 184 | */ |
1d8cc731 | 185 | GIT_EXTERN(int) git_reference_set_oid(git_reference *ref, const git_oid *id); |
2f8a8ab2 | 186 | |
32054c24 VM |
187 | /** |
188 | * Rename an existing reference | |
189 | * | |
190 | * This method works for both direct and symbolic references. | |
191 | * The new name will be checked for validity and may be | |
192 | * modified into a normalized form. | |
193 | * | |
194 | * The refernece will be immediately renamed in-memory | |
195 | * and on disk. | |
196 | * | |
197 | */ | |
7376ad99 | 198 | GIT_EXTERN(int) git_reference_rename(git_reference *ref, const char *new_name, int force); |
fa204962 | 199 | |
32054c24 VM |
200 | /** |
201 | * Delete an existing reference | |
202 | * | |
203 | * This method works for both direct and symbolic references. | |
204 | * | |
205 | * The reference will be immediately removed on disk and from | |
206 | * memory. The given reference pointer will no longer be valid. | |
207 | * | |
208 | */ | |
209 | GIT_EXTERN(int) git_reference_delete(git_reference *ref); | |
210 | ||
87d3acf4 VM |
211 | /** |
212 | * Pack all the loose references in the repository | |
213 | * | |
214 | * This method will load into the cache all the loose | |
215 | * references on the repository and update the | |
216 | * `packed-refs` file with them. | |
217 | * | |
218 | * Once the `packed-refs` file has been written properly, | |
219 | * the loose references will be removed from disk. | |
220 | * | |
221 | * WARNING: calling this method may invalidate any existing | |
222 | * references previously loaded on the cache. | |
223 | * | |
224 | * @param repo Repository where the loose refs will be packed | |
225 | * @return 0 on success; error code otherwise | |
226 | */ | |
227 | GIT_EXTERN(int) git_reference_packall(git_repository *repo); | |
228 | ||
00571828 VM |
229 | /** |
230 | * Fill a list with all the references that can be found | |
231 | * in a repository. | |
232 | * | |
233 | * The listed references may be filtered by type, or using | |
234 | * a bitwise OR of several types. Use the magic value | |
235 | * `GIT_REF_LISTALL` to obtain all references, including | |
236 | * packed ones. | |
237 | * | |
238 | * The string array will be filled with the names of all | |
239 | * references; these values are owned by the user and | |
240 | * should be free'd manually when no longer needed, using | |
241 | * `git_strarray_free`. | |
242 | * | |
243 | * @param array Pointer to a git_strarray structure where | |
244 | * the reference names will be stored | |
245 | * @param repo Repository where to find the refs | |
246 | * @param list_flags Filtering flags for the reference | |
247 | * listing. | |
248 | * @return 0 on success; error code otherwise | |
249 | */ | |
250 | GIT_EXTERN(int) git_reference_listall(git_strarray *array, git_repository *repo, unsigned int list_flags); | |
251 | ||
09e8de0f VM |
252 | |
253 | /** | |
43521d06 | 254 | * Perform an operation on each reference in the repository |
09e8de0f | 255 | * |
43521d06 | 256 | * The processed references may be filtered by type, or using |
09e8de0f VM |
257 | * a bitwise OR of several types. Use the magic value |
258 | * `GIT_REF_LISTALL` to obtain all references, including | |
259 | * packed ones. | |
260 | * | |
261 | * The `callback` function will be called for each of the references | |
262 | * in the repository, and will receive the name of the reference and | |
263 | * the `payload` value passed to this method. | |
264 | * | |
265 | * @param repo Repository where to find the refs | |
266 | * @param list_flags Filtering flags for the reference | |
267 | * listing. | |
268 | * @param callback Function which will be called for every listed ref | |
269 | * @param payload Additional data to pass to the callback | |
270 | * @return 0 on success; error code otherwise | |
271 | */ | |
43521d06 | 272 | GIT_EXTERN(int) git_reference_foreach(git_repository *repo, unsigned int list_flags, int (*callback)(const char *, void *), void *payload); |
09e8de0f | 273 | |
2f8a8ab2 VM |
274 | /** @} */ |
275 | GIT_END_DECL | |
276 | #endif |