]>
Commit | Line | Data |
---|---|---|
2f8a8ab2 | 1 | /* |
359fc2d2 | 2 | * Copyright (C) the libgit2 contributors. All rights reserved. |
2f8a8ab2 | 3 | * |
bb742ede VM |
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. | |
2f8a8ab2 VM |
6 | */ |
7 | #ifndef INCLUDE_git_refs_h__ | |
8 | #define INCLUDE_git_refs_h__ | |
9 | ||
10 | #include "common.h" | |
11 | #include "types.h" | |
fc70832a | 12 | #include "oid.h" |
b46708aa | 13 | #include "strarray.h" |
2f8a8ab2 VM |
14 | |
15 | /** | |
16 | * @file git2/refs.h | |
17 | * @brief Git reference management routines | |
18 | * @defgroup git_reference Git reference management routines | |
19 | * @ingroup Git | |
20 | * @{ | |
21 | */ | |
22 | GIT_BEGIN_DECL | |
23 | ||
5de079b8 | 24 | /** |
b90500f0 | 25 | * Lookup a reference by name in a repository. |
5de079b8 | 26 | * |
b90500f0 RB |
27 | * The returned reference must be freed by the user. |
28 | * | |
80d9d1df | 29 | * The name will be checked for validity. |
3f0e3e16 | 30 | * See `git_reference_symbolic_create()` for rules about valid names. |
5de079b8 | 31 | * |
2508cc66 | 32 | * @param out pointer to the looked-up reference |
5de079b8 | 33 | * @param repo the repository to look up the reference |
b90500f0 | 34 | * @param name the long name for the reference (e.g. HEAD, refs/heads/master, refs/tags/v0.1.0, ...) |
0b170f4d | 35 | * @return 0 on success, GIT_ENOTFOUND, GIT_EINVALIDSPEC or an error code. |
5de079b8 | 36 | */ |
2508cc66 | 37 | GIT_EXTERN(int) git_reference_lookup(git_reference **out, git_repository *repo, const char *name); |
5de079b8 | 38 | |
f201d613 RB |
39 | /** |
40 | * Lookup a reference by name and resolve immediately to OID. | |
41 | * | |
b90500f0 RB |
42 | * This function provides a quick way to resolve a reference name straight |
43 | * through to the object id that it refers to. This avoids having to | |
44 | * allocate or free any `git_reference` objects for simple situations. | |
45 | * | |
80d9d1df | 46 | * The name will be checked for validity. |
087f64d3 | 47 | * See `git_reference_symbolic_create()` for rules about valid names. |
80d9d1df | 48 | * |
2508cc66 | 49 | * @param out Pointer to oid to be filled in |
f201d613 | 50 | * @param repo The repository in which to look up the reference |
e069478e | 51 | * @param name The long name for the reference (e.g. HEAD, refs/heads/master, refs/tags/v0.1.0, ...) |
0b170f4d | 52 | * @return 0 on success, GIT_ENOTFOUND, GIT_EINVALIDSPEC or an error code. |
f201d613 | 53 | */ |
2508cc66 | 54 | GIT_EXTERN(int) git_reference_name_to_id( |
26515e73 | 55 | git_oid *out, git_repository *repo, const char *name); |
f201d613 | 56 | |
98d633cc CMN |
57 | /** |
58 | * Lookup a reference by DWIMing its short name | |
59 | * | |
e579e0f7 | 60 | * Apply the git precedence rules to the given shorthand to determine |
b874629b | 61 | * which reference the user is referring to. |
98d633cc CMN |
62 | * |
63 | * @param out pointer in which to store the reference | |
64 | * @param repo the repository in which to look | |
e1967164 | 65 | * @param shorthand the short name for the reference |
98d633cc CMN |
66 | * @return 0 or an error code |
67 | */ | |
68 | GIT_EXTERN(int) git_reference_dwim(git_reference **out, git_repository *repo, const char *shorthand); | |
69 | ||
878fb66f CMN |
70 | /** |
71 | * Conditionally create a new symbolic reference. | |
72 | * | |
73 | * A symbolic reference is a reference name that refers to another | |
74 | * reference name. If the other name moves, the symbolic name will move, | |
75 | * too. As a simple example, the "HEAD" reference might refer to | |
76 | * "refs/heads/master" while on the "master" branch of a repository. | |
77 | * | |
78 | * The symbolic reference will be created in the repository and written to | |
79 | * the disk. The generated reference object must be freed by the user. | |
80 | * | |
81 | * Valid reference names must follow one of two patterns: | |
82 | * | |
83 | * 1. Top-level names must contain only capital letters and underscores, | |
84 | * and must begin and end with a letter. (e.g. "HEAD", "ORIG_HEAD"). | |
85 | * 2. Names prefixed with "refs/" can be almost anything. You must avoid | |
86 | * the characters '~', '^', ':', '\\', '?', '[', and '*', and the | |
87 | * sequences ".." and "@{" which have special meaning to revparse. | |
88 | * | |
89 | * This function will return an error if a reference already exists with the | |
90 | * given name unless `force` is true, in which case it will be overwritten. | |
91 | * | |
659cf202 CMN |
92 | * The message for the reflog will be ignored if the reference does |
93 | * not belong in the standard set (HEAD, branches and remote-tracking | |
94 | * branches) and it does not have a reflog. | |
878fb66f | 95 | * |
77ad6754 CMN |
96 | * It will return GIT_EMODIFIED if the reference's value at the time |
97 | * of updating does not match the one passed through `current_value` | |
98 | * (i.e. if the ref has changed since the user read it). | |
878fb66f | 99 | * |
c25aa7cd PP |
100 | * If `current_value` is all zeros, this function will return GIT_EMODIFIED |
101 | * if the ref already exists. | |
102 | * | |
878fb66f CMN |
103 | * @param out Pointer to the newly created reference |
104 | * @param repo Repository where that reference will live | |
105 | * @param name The name of the reference | |
106 | * @param target The target of the reference | |
107 | * @param force Overwrite existing references | |
15284a2c | 108 | * @param current_value The expected value of the reference when updating |
878fb66f CMN |
109 | * @param log_message The one line long message to be appended to the reflog |
110 | * @return 0 on success, GIT_EEXISTS, GIT_EINVALIDSPEC, GIT_EMODIFIED or an error code | |
111 | */ | |
659cf202 | 112 | GIT_EXTERN(int) git_reference_symbolic_create_matching(git_reference **out, git_repository *repo, const char *name, const char *target, int force, const char *current_value, const char *log_message); |
878fb66f | 113 | |
2f8a8ab2 | 114 | /** |
1d8cc731 | 115 | * Create a new symbolic reference. |
2f8a8ab2 | 116 | * |
b90500f0 RB |
117 | * A symbolic reference is a reference name that refers to another |
118 | * reference name. If the other name moves, the symbolic name will move, | |
119 | * too. As a simple example, the "HEAD" reference might refer to | |
120 | * "refs/heads/master" while on the "master" branch of a repository. | |
121 | * | |
122 | * The symbolic reference will be created in the repository and written to | |
123 | * the disk. The generated reference object must be freed by the user. | |
124 | * | |
125 | * Valid reference names must follow one of two patterns: | |
2f8a8ab2 | 126 | * |
b90500f0 RB |
127 | * 1. Top-level names must contain only capital letters and underscores, |
128 | * and must begin and end with a letter. (e.g. "HEAD", "ORIG_HEAD"). | |
129 | * 2. Names prefixed with "refs/" can be almost anything. You must avoid | |
130 | * the characters '~', '^', ':', '\\', '?', '[', and '*', and the | |
131 | * sequences ".." and "@{" which have special meaning to revparse. | |
32054c24 | 132 | * |
b90500f0 RB |
133 | * This function will return an error if a reference already exists with the |
134 | * given name unless `force` is true, in which case it will be overwritten. | |
fa204962 | 135 | * |
659cf202 CMN |
136 | * The message for the reflog will be ignored if the reference does |
137 | * not belong in the standard set (HEAD, branches and remote-tracking | |
138 | * branches) and it does not have a reflog. | |
56ad3782 | 139 | * |
140 | * @param out Pointer to the newly created reference | |
141 | * @param repo Repository where that reference will live | |
142 | * @param name The name of the reference | |
143 | * @param target The target of the reference | |
144 | * @param force Overwrite existing references | |
0b28217b CMN |
145 | * @param log_message The one line long message to be appended to the reflog |
146 | * @return 0 on success, GIT_EEXISTS, GIT_EINVALIDSPEC or an error code | |
56ad3782 | 147 | */ |
659cf202 | 148 | GIT_EXTERN(int) git_reference_symbolic_create(git_reference **out, git_repository *repo, const char *name, const char *target, int force, const char *log_message); |
56ad3782 | 149 | |
1d8cc731 | 150 | /** |
b90500f0 | 151 | * Create a new direct reference. |
1d8cc731 | 152 | * |
b90500f0 RB |
153 | * A direct reference (also called an object id reference) refers directly |
154 | * to a specific object id (a.k.a. OID or SHA) in the repository. The id | |
155 | * permanently refers to the object (although the reference itself can be | |
156 | * moved). For example, in libgit2 the direct ref "refs/tags/v0.17.0" | |
157 | * refers to OID 5b9fac39d8a76b9139667c26a63e6b3f204b3977. | |
1d8cc731 | 158 | * |
b90500f0 RB |
159 | * The direct reference will be created in the repository and written to |
160 | * the disk. The generated reference object must be freed by the user. | |
32054c24 | 161 | * |
b90500f0 RB |
162 | * Valid reference names must follow one of two patterns: |
163 | * | |
164 | * 1. Top-level names must contain only capital letters and underscores, | |
165 | * and must begin and end with a letter. (e.g. "HEAD", "ORIG_HEAD"). | |
166 | * 2. Names prefixed with "refs/" can be almost anything. You must avoid | |
167 | * the characters '~', '^', ':', '\\', '?', '[', and '*', and the | |
168 | * sequences ".." and "@{" which have special meaning to revparse. | |
169 | * | |
170 | * This function will return an error if a reference already exists with the | |
171 | * given name unless `force` is true, in which case it will be overwritten. | |
fa204962 | 172 | * |
659cf202 CMN |
173 | * The message for the reflog will be ignored if the reference does |
174 | * not belong in the standard set (HEAD, branches and remote-tracking | |
c25aa7cd | 175 | * branches) and it does not have a reflog. |
bba25f39 | 176 | * |
177 | * @param out Pointer to the newly created reference | |
178 | * @param repo Repository where that reference will live | |
179 | * @param name The name of the reference | |
180 | * @param id The object id pointed to by the reference. | |
181 | * @param force Overwrite existing references | |
0b28217b CMN |
182 | * @param log_message The one line long message to be appended to the reflog |
183 | * @return 0 on success, GIT_EEXISTS, GIT_EINVALIDSPEC or an error code | |
bba25f39 | 184 | */ |
659cf202 | 185 | GIT_EXTERN(int) git_reference_create(git_reference **out, git_repository *repo, const char *name, const git_oid *id, int force, const char *log_message); |
bba25f39 | 186 | |
9b148098 CMN |
187 | /** |
188 | * Conditionally create new direct reference | |
189 | * | |
190 | * A direct reference (also called an object id reference) refers directly | |
191 | * to a specific object id (a.k.a. OID or SHA) in the repository. The id | |
192 | * permanently refers to the object (although the reference itself can be | |
193 | * moved). For example, in libgit2 the direct ref "refs/tags/v0.17.0" | |
194 | * refers to OID 5b9fac39d8a76b9139667c26a63e6b3f204b3977. | |
195 | * | |
196 | * The direct reference will be created in the repository and written to | |
197 | * the disk. The generated reference object must be freed by the user. | |
198 | * | |
199 | * Valid reference names must follow one of two patterns: | |
200 | * | |
201 | * 1. Top-level names must contain only capital letters and underscores, | |
202 | * and must begin and end with a letter. (e.g. "HEAD", "ORIG_HEAD"). | |
203 | * 2. Names prefixed with "refs/" can be almost anything. You must avoid | |
204 | * the characters '~', '^', ':', '\\', '?', '[', and '*', and the | |
205 | * sequences ".." and "@{" which have special meaning to revparse. | |
206 | * | |
207 | * This function will return an error if a reference already exists with the | |
208 | * given name unless `force` is true, in which case it will be overwritten. | |
209 | * | |
659cf202 CMN |
210 | * The message for the reflog will be ignored if the reference does |
211 | * not belong in the standard set (HEAD, branches and remote-tracking | |
c25aa7cd | 212 | * branches) and it does not have a reflog. |
9b148098 | 213 | * |
77ad6754 CMN |
214 | * It will return GIT_EMODIFIED if the reference's value at the time |
215 | * of updating does not match the one passed through `current_id` | |
216 | * (i.e. if the ref has changed since the user read it). | |
9b148098 CMN |
217 | * |
218 | * @param out Pointer to the newly created reference | |
219 | * @param repo Repository where that reference will live | |
220 | * @param name The name of the reference | |
221 | * @param id The object id pointed to by the reference. | |
222 | * @param force Overwrite existing references | |
15284a2c | 223 | * @param current_id The expected value of the reference at the time of update |
9b148098 | 224 | * @param log_message The one line long message to be appended to the reflog |
fc4728e3 CMN |
225 | * @return 0 on success, GIT_EMODIFIED if the value of the reference |
226 | * has changed, GIT_EEXISTS, GIT_EINVALIDSPEC or an error code | |
9b148098 | 227 | */ |
659cf202 | 228 | GIT_EXTERN(int) git_reference_create_matching(git_reference **out, git_repository *repo, const char *name, const git_oid *id, int force, const git_oid *current_id, const char *log_message); |
9b148098 | 229 | |
2f8a8ab2 | 230 | /** |
b90500f0 RB |
231 | * Get the OID pointed to by a direct reference. |
232 | * | |
233 | * Only available if the reference is direct (i.e. an object id reference, | |
234 | * not a symbolic one). | |
932d1baf | 235 | * |
b90500f0 | 236 | * To find the OID of a symbolic ref, call `git_reference_resolve()` and |
abeefbbe | 237 | * then this function (or maybe use `git_reference_name_to_id()` to |
b90500f0 | 238 | * directly resolve a reference name all the way through to an OID). |
2f8a8ab2 VM |
239 | * |
240 | * @param ref The reference | |
241 | * @return a pointer to the oid if available, NULL otherwise | |
242 | */ | |
2508cc66 | 243 | GIT_EXTERN(const git_oid *) git_reference_target(const git_reference *ref); |
2f8a8ab2 | 244 | |
3be933b1 VM |
245 | /** |
246 | * Return the peeled OID target of this reference. | |
247 | * | |
248 | * This peeled OID only applies to direct references that point to | |
249 | * a hard Tag object: it is the result of peeling such Tag. | |
250 | * | |
251 | * @param ref The reference | |
252 | * @return a pointer to the oid if available, NULL otherwise | |
253 | */ | |
254 | GIT_EXTERN(const git_oid *) git_reference_target_peel(const git_reference *ref); | |
255 | ||
2f8a8ab2 | 256 | /** |
b90500f0 | 257 | * Get full name to the reference pointed to by a symbolic reference. |
932d1baf | 258 | * |
b90500f0 | 259 | * Only available if the reference is symbolic. |
2f8a8ab2 VM |
260 | * |
261 | * @param ref The reference | |
262 | * @return a pointer to the name if available, NULL otherwise | |
263 | */ | |
2508cc66 | 264 | GIT_EXTERN(const char *) git_reference_symbolic_target(const git_reference *ref); |
2f8a8ab2 VM |
265 | |
266 | /** | |
b90500f0 | 267 | * Get the type of a reference. |
2f8a8ab2 | 268 | * |
ac3d33df | 269 | * Either direct (GIT_REFERENCE_DIRECT) or symbolic (GIT_REFERENCE_SYMBOLIC) |
2f8a8ab2 VM |
270 | * |
271 | * @param ref The reference | |
272 | * @return the type | |
273 | */ | |
ac3d33df | 274 | GIT_EXTERN(git_reference_t) git_reference_type(const git_reference *ref); |
2f8a8ab2 VM |
275 | |
276 | /** | |
b90500f0 RB |
277 | * Get the full name of a reference. |
278 | * | |
3f0e3e16 | 279 | * See `git_reference_symbolic_create()` for rules about valid names. |
2f8a8ab2 VM |
280 | * |
281 | * @param ref The reference | |
282 | * @return the full name for the ref | |
283 | */ | |
2508cc66 | 284 | GIT_EXTERN(const char *) git_reference_name(const git_reference *ref); |
2f8a8ab2 VM |
285 | |
286 | /** | |
b90500f0 | 287 | * Resolve a symbolic reference to a direct reference. |
2f8a8ab2 | 288 | * |
b90500f0 RB |
289 | * This method iteratively peels a symbolic reference until it resolves to |
290 | * a direct reference to an OID. | |
2f8a8ab2 | 291 | * |
b90500f0 RB |
292 | * The peeled reference is returned in the `resolved_ref` argument, and |
293 | * must be freed manually once it's no longer needed. | |
d4a0b124 | 294 | * |
b90500f0 RB |
295 | * If a direct reference is passed as an argument, a copy of that |
296 | * reference is returned. This copy must be manually freed too. | |
2f8a8ab2 | 297 | * |
e1967164 | 298 | * @param out Pointer to the peeled reference |
2f8a8ab2 | 299 | * @param ref The reference |
e172cf08 | 300 | * @return 0 or an error code |
2f8a8ab2 | 301 | */ |
2508cc66 | 302 | GIT_EXTERN(int) git_reference_resolve(git_reference **out, const git_reference *ref); |
2f8a8ab2 | 303 | |
2f8a8ab2 | 304 | /** |
b90500f0 | 305 | * Get the repository where a reference resides. |
2f8a8ab2 VM |
306 | * |
307 | * @param ref The reference | |
308 | * @return a pointer to the repo | |
309 | */ | |
2508cc66 | 310 | GIT_EXTERN(git_repository *) git_reference_owner(const git_reference *ref); |
2f8a8ab2 | 311 | |
2f8a8ab2 | 312 | /** |
d00d5464 ET |
313 | * Create a new reference with the same name as the given reference but a |
314 | * different symbolic target. The reference must be a symbolic reference, | |
315 | * otherwise this will fail. | |
2f8a8ab2 | 316 | * |
d00d5464 | 317 | * The new reference will be written to disk, overwriting the given reference. |
2f8a8ab2 | 318 | * |
80d9d1df | 319 | * The target name will be checked for validity. |
3f0e3e16 | 320 | * See `git_reference_symbolic_create()` for rules about valid names. |
80d9d1df | 321 | * |
659cf202 CMN |
322 | * The message for the reflog will be ignored if the reference does |
323 | * not belong in the standard set (HEAD, branches and remote-tracking | |
c25aa7cd | 324 | * branches) and it does not have a reflog. |
ca84e058 | 325 | * |
326 | * @param out Pointer to the newly created reference | |
327 | * @param ref The reference | |
328 | * @param target The new target for the reference | |
0b28217b CMN |
329 | * @param log_message The one line long message to be appended to the reflog |
330 | * @return 0 on success, GIT_EINVALIDSPEC or an error code | |
ca84e058 | 331 | */ |
0b28217b | 332 | GIT_EXTERN(int) git_reference_symbolic_set_target( |
ca84e058 | 333 | git_reference **out, |
334 | git_reference *ref, | |
335 | const char *target, | |
ca84e058 | 336 | const char *log_message); |
337 | ||
2f8a8ab2 | 338 | /** |
9b148098 | 339 | * Conditionally create a new reference with the same name as the given reference but a |
d00d5464 ET |
340 | * different OID target. The reference must be a direct reference, otherwise |
341 | * this will fail. | |
2f8a8ab2 | 342 | * |
d00d5464 | 343 | * The new reference will be written to disk, overwriting the given reference. |
2f8a8ab2 | 344 | * |
14ab0e10 | 345 | * @param out Pointer to the newly created reference |
346 | * @param ref The reference | |
347 | * @param id The new target OID for the reference | |
0b28217b | 348 | * @param log_message The one line long message to be appended to the reflog |
fc4728e3 | 349 | * @return 0 on success, GIT_EMODIFIED if the value of the reference |
77ad6754 | 350 | * has changed since it was read, or an error code |
14ab0e10 | 351 | */ |
0b28217b | 352 | GIT_EXTERN(int) git_reference_set_target( |
14ab0e10 | 353 | git_reference **out, |
354 | git_reference *ref, | |
355 | const git_oid *id, | |
14ab0e10 | 356 | const char *log_message); |
357 | ||
32054c24 | 358 | /** |
b90500f0 | 359 | * Rename an existing reference. |
32054c24 VM |
360 | * |
361 | * This method works for both direct and symbolic references. | |
80d9d1df | 362 | * |
363 | * The new name will be checked for validity. | |
3f0e3e16 | 364 | * See `git_reference_symbolic_create()` for rules about valid names. |
32054c24 | 365 | * |
d4a0b124 VM |
366 | * If the `force` flag is not enabled, and there's already |
367 | * a reference with the given name, the renaming will fail. | |
368 | * | |
a5cd086d MS |
369 | * IMPORTANT: |
370 | * The user needs to write a proper reflog entry if the | |
371 | * reflog is enabled for the repository. We only rename | |
372 | * the reflog if it exists. | |
373 | * | |
d4a0b124 | 374 | * @param ref The reference to rename |
e1967164 | 375 | * @param new_name The new name for the reference |
d4a0b124 | 376 | * @param force Overwrite an existing reference |
ccf6ce5c | 377 | * @param log_message The one line long message to be appended to the reflog |
0b170f4d | 378 | * @return 0 on success, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code |
d4a0b124 | 379 | * |
32054c24 | 380 | */ |
d00d5464 | 381 | GIT_EXTERN(int) git_reference_rename( |
4e6e2ff2 | 382 | git_reference **new_ref, |
d00d5464 ET |
383 | git_reference *ref, |
384 | const char *new_name, | |
ccf6ce5c | 385 | int force, |
ccf6ce5c | 386 | const char *log_message); |
fa204962 | 387 | |
32054c24 | 388 | /** |
b90500f0 | 389 | * Delete an existing reference. |
32054c24 | 390 | * |
d00d5464 ET |
391 | * This method works for both direct and symbolic references. The reference |
392 | * will be immediately removed on disk but the memory will not be freed. | |
393 | * Callers must call `git_reference_free`. | |
32054c24 | 394 | * |
f44fd59e CMN |
395 | * This function will return an error if the reference has changed |
396 | * from the time it was looked up. | |
397 | * | |
d4a0b124 | 398 | * @param ref The reference to remove |
f44fd59e | 399 | * @return 0, GIT_EMODIFIED or an error code |
32054c24 VM |
400 | */ |
401 | GIT_EXTERN(int) git_reference_delete(git_reference *ref); | |
402 | ||
5367ec4b CMN |
403 | /** |
404 | * Delete an existing reference by name | |
405 | * | |
406 | * This method removes the named reference from the repository without | |
407 | * looking at its old value. | |
408 | * | |
31b0cb51 | 409 | * @param name The reference to remove |
2b40390f | 410 | * @return 0 or an error code |
5367ec4b CMN |
411 | */ |
412 | GIT_EXTERN(int) git_reference_remove(git_repository *repo, const char *name); | |
413 | ||
00571828 | 414 | /** |
b90500f0 | 415 | * Fill a list with all the references that can be found in a repository. |
00571828 | 416 | * |
b90500f0 RB |
417 | * The string array will be filled with the names of all references; these |
418 | * values are owned by the user and should be free'd manually when no | |
419 | * longer needed, using `git_strarray_free()`. | |
00571828 VM |
420 | * |
421 | * @param array Pointer to a git_strarray structure where | |
422 | * the reference names will be stored | |
423 | * @param repo Repository where to find the refs | |
e172cf08 | 424 | * @return 0 or an error code |
00571828 | 425 | */ |
2b562c3a | 426 | GIT_EXTERN(int) git_reference_list(git_strarray *array, git_repository *repo); |
00571828 | 427 | |
22a2d3d5 UG |
428 | /** |
429 | * Callback used to iterate over references | |
430 | * | |
431 | * @see git_reference_foreach | |
432 | * | |
433 | * @param reference The reference object | |
434 | * @param payload Payload passed to git_reference_foreach | |
435 | * @return non-zero to terminate the iteration | |
436 | */ | |
ac3d33df | 437 | typedef int GIT_CALLBACK(git_reference_foreach_cb)(git_reference *reference, void *payload); |
22a2d3d5 UG |
438 | |
439 | /** | |
440 | * Callback used to iterate over reference names | |
441 | * | |
442 | * @see git_reference_foreach_name | |
443 | * | |
444 | * @param name The reference name | |
445 | * @param payload Payload passed to git_reference_foreach_name | |
446 | * @return non-zero to terminate the iteration | |
447 | */ | |
ac3d33df | 448 | typedef int GIT_CALLBACK(git_reference_foreach_name_cb)(const char *name, void *payload); |
eecc8050 | 449 | |
09e8de0f | 450 | /** |
b90500f0 | 451 | * Perform a callback on each reference in the repository. |
09e8de0f | 452 | * |
b90500f0 | 453 | * The `callback` function will be called for each reference in the |
373cf6a9 | 454 | * repository, receiving the reference object and the `payload` value |
b90500f0 RB |
455 | * passed to this method. Returning a non-zero value from the callback |
456 | * will terminate the iteration. | |
09e8de0f | 457 | * |
eae0bfdc PP |
458 | * Note that the callback function is responsible to call `git_reference_free` |
459 | * on each reference passed to it. | |
460 | * | |
09e8de0f | 461 | * @param repo Repository where to find the refs |
09e8de0f VM |
462 | * @param callback Function which will be called for every listed ref |
463 | * @param payload Additional data to pass to the callback | |
373cf6a9 | 464 | * @return 0 on success, non-zero callback return value, or error code |
09e8de0f | 465 | */ |
eecc8050 RB |
466 | GIT_EXTERN(int) git_reference_foreach( |
467 | git_repository *repo, | |
eecc8050 RB |
468 | git_reference_foreach_cb callback, |
469 | void *payload); | |
09e8de0f | 470 | |
373cf6a9 RB |
471 | /** |
472 | * Perform a callback on the fully-qualified name of each reference. | |
473 | * | |
474 | * The `callback` function will be called for each reference in the | |
475 | * repository, receiving the name of the reference and the `payload` value | |
476 | * passed to this method. Returning a non-zero value from the callback | |
477 | * will terminate the iteration. | |
478 | * | |
479 | * @param repo Repository where to find the refs | |
480 | * @param callback Function which will be called for every listed ref name | |
481 | * @param payload Additional data to pass to the callback | |
482 | * @return 0 on success, non-zero callback return value, or error code | |
483 | */ | |
ec24e542 VM |
484 | GIT_EXTERN(int) git_reference_foreach_name( |
485 | git_repository *repo, | |
486 | git_reference_foreach_name_cb callback, | |
487 | void *payload); | |
488 | ||
908f24fd AS |
489 | /** |
490 | * Create a copy of an existing reference. | |
491 | * | |
492 | * Call `git_reference_free` to free the data. | |
493 | * | |
494 | * @param dest pointer where to store the copy | |
495 | * @param source object to copy | |
496 | * @return 0 or an error code | |
497 | */ | |
498 | GIT_EXTERN(int) git_reference_dup(git_reference **dest, git_reference *source); | |
499 | ||
a46ec457 | 500 | /** |
b90500f0 | 501 | * Free the given reference. |
a46ec457 MS |
502 | * |
503 | * @param ref git_reference | |
504 | */ | |
505 | GIT_EXTERN(void) git_reference_free(git_reference *ref); | |
506 | ||
f201d613 RB |
507 | /** |
508 | * Compare two references. | |
509 | * | |
510 | * @param ref1 The first git_reference | |
511 | * @param ref2 The second git_reference | |
e172cf08 | 512 | * @return 0 if the same, else a stable but meaningless ordering. |
f201d613 | 513 | */ |
3b4ba278 JG |
514 | GIT_EXTERN(int) git_reference_cmp( |
515 | const git_reference *ref1, | |
516 | const git_reference *ref2); | |
f201d613 | 517 | |
4def7035 CMN |
518 | /** |
519 | * Create an iterator for the repo's references | |
520 | * | |
521 | * @param out pointer in which to store the iterator | |
522 | * @param repo the repository | |
523 | * @return 0 or an error code | |
524 | */ | |
56960b83 VM |
525 | GIT_EXTERN(int) git_reference_iterator_new( |
526 | git_reference_iterator **out, | |
527 | git_repository *repo); | |
4def7035 | 528 | |
fc74343f CMN |
529 | /** |
530 | * Create an iterator for the repo's references that match the | |
531 | * specified glob | |
532 | * | |
533 | * @param out pointer in which to store the iterator | |
534 | * @param repo the repository | |
535 | * @param glob the glob to match against the reference names | |
536 | * @return 0 or an error code | |
537 | */ | |
56960b83 VM |
538 | GIT_EXTERN(int) git_reference_iterator_glob_new( |
539 | git_reference_iterator **out, | |
540 | git_repository *repo, | |
541 | const char *glob); | |
fc74343f | 542 | |
4def7035 | 543 | /** |
56960b83 | 544 | * Get the next reference |
4def7035 | 545 | * |
56960b83 | 546 | * @param out pointer in which to store the reference |
4def7035 | 547 | * @param iter the iterator |
e1967164 | 548 | * @return 0, GIT_ITEROVER if there are no more; or an error code |
4def7035 | 549 | */ |
56960b83 | 550 | GIT_EXTERN(int) git_reference_next(git_reference **out, git_reference_iterator *iter); |
4def7035 | 551 | |
891b0277 CMN |
552 | /** |
553 | * Get the next reference's name | |
554 | * | |
555 | * This function is provided for convenience in case only the names | |
556 | * are interesting as it avoids the allocation of the `git_reference` | |
557 | * object which `git_reference_next()` needs. | |
558 | * | |
559 | * @param out pointer in which to store the string | |
560 | * @param iter the iterator | |
561 | * @return 0, GIT_ITEROVER if there are no more; or an error code | |
562 | */ | |
ec24e542 | 563 | GIT_EXTERN(int) git_reference_next_name(const char **out, git_reference_iterator *iter); |
4def7035 CMN |
564 | |
565 | /** | |
566 | * Free the iterator and its associated resources | |
567 | * | |
568 | * @param iter the iterator to free | |
569 | */ | |
570 | GIT_EXTERN(void) git_reference_iterator_free(git_reference_iterator *iter); | |
571 | ||
527ed554 | 572 | /** |
b90500f0 RB |
573 | * Perform a callback on each reference in the repository whose name |
574 | * matches the given pattern. | |
527ed554 | 575 | * |
b90500f0 RB |
576 | * This function acts like `git_reference_foreach()` with an additional |
577 | * pattern match being applied to the reference name before issuing the | |
578 | * callback function. See that function for more information. | |
e0db9f11 | 579 | * |
b90500f0 RB |
580 | * The pattern is matched using fnmatch or "glob" style where a '*' matches |
581 | * any sequence of letters, a '?' matches any letter, and square brackets | |
582 | * can be used to define character ranges (such as "[0-9]" for digits). | |
527ed554 | 583 | * |
b90500f0 RB |
584 | * @param repo Repository where to find the refs |
585 | * @param glob Pattern to match (fnmatch-style) against reference name. | |
b90500f0 RB |
586 | * @param callback Function which will be called for every listed ref |
587 | * @param payload Additional data to pass to the callback | |
588 | * @return 0 on success, GIT_EUSER on non-zero callback, or error code | |
527ed554 | 589 | */ |
590 | GIT_EXTERN(int) git_reference_foreach_glob( | |
b90500f0 RB |
591 | git_repository *repo, |
592 | const char *glob, | |
ec24e542 | 593 | git_reference_foreach_name_cb callback, |
b90500f0 | 594 | void *payload); |
527ed554 | 595 | |
75261421 | 596 | /** |
597 | * Check if a reflog exists for the specified reference. | |
598 | * | |
f2105129 CMN |
599 | * @param repo the repository |
600 | * @param refname the reference's name | |
75261421 | 601 | * @return 0 when no reflog can be found, 1 when it exists; |
602 | * otherwise an error code. | |
603 | */ | |
f2105129 | 604 | GIT_EXTERN(int) git_reference_has_log(git_repository *repo, const char *refname); |
75261421 | 605 | |
8d5ec910 CMN |
606 | /** |
607 | * Ensure there is a reflog for a particular reference. | |
608 | * | |
609 | * Make sure that successive updates to the reference will append to | |
610 | * its log. | |
611 | * | |
612 | * @param repo the repository | |
613 | * @param refname the reference's name | |
614 | * @return 0 or an error code. | |
615 | */ | |
616 | GIT_EXTERN(int) git_reference_ensure_log(git_repository *repo, const char *refname); | |
75261421 | 617 | |
88bcd515 | 618 | /** |
619 | * Check if a reference is a local branch. | |
620 | * | |
621 | * @param ref A git reference | |
622 | * | |
623 | * @return 1 when the reference lives in the refs/heads | |
624 | * namespace; 0 otherwise. | |
625 | */ | |
853b1407 | 626 | GIT_EXTERN(int) git_reference_is_branch(const git_reference *ref); |
88bcd515 | 627 | |
1c947daa VM |
628 | /** |
629 | * Check if a reference is a remote tracking branch | |
630 | * | |
631 | * @param ref A git reference | |
632 | * | |
633 | * @return 1 when the reference lives in the refs/remotes | |
634 | * namespace; 0 otherwise. | |
635 | */ | |
3b4ba278 | 636 | GIT_EXTERN(int) git_reference_is_remote(const git_reference *ref); |
1c947daa | 637 | |
504850cd NV |
638 | /** |
639 | * Check if a reference is a tag | |
640 | * | |
641 | * @param ref A git reference | |
642 | * | |
643 | * @return 1 when the reference lives in the refs/tags | |
644 | * namespace; 0 otherwise. | |
645 | */ | |
3b4ba278 | 646 | GIT_EXTERN(int) git_reference_is_tag(const git_reference *ref); |
b90500f0 | 647 | |
50ad7cc2 AS |
648 | /** |
649 | * Check if a reference is a note | |
650 | * | |
651 | * @param ref A git reference | |
652 | * | |
653 | * @return 1 when the reference lives in the refs/notes | |
654 | * namespace; 0 otherwise. | |
655 | */ | |
3b4ba278 | 656 | GIT_EXTERN(int) git_reference_is_note(const git_reference *ref); |
50ad7cc2 | 657 | |
a295bd2d CMN |
658 | /** |
659 | * Normalization options for reference lookup | |
660 | */ | |
b90500f0 | 661 | typedef enum { |
a295bd2d CMN |
662 | /** |
663 | * No particular normalization. | |
664 | */ | |
ac3d33df | 665 | GIT_REFERENCE_FORMAT_NORMAL = 0u, |
2e0c8816 | 666 | |
667 | /** | |
668 | * Control whether one-level refnames are accepted | |
669 | * (i.e., refnames that do not contain multiple /-separated | |
77e06d7e | 670 | * components). Those are expected to be written only using |
671 | * uppercase letters and underscore (FETCH_HEAD, ...) | |
2e0c8816 | 672 | */ |
ac3d33df | 673 | GIT_REFERENCE_FORMAT_ALLOW_ONELEVEL = (1u << 0), |
2e0c8816 | 674 | |
675 | /** | |
676 | * Interpret the provided name as a reference pattern for a | |
677 | * refspec (as used with remote repositories). If this option | |
678 | * is enabled, the name is allowed to contain a single * (<star>) | |
679 | * in place of a one full pathname component | |
680 | * (e.g., foo/<star>/bar but not foo/bar<star>). | |
681 | */ | |
ac3d33df | 682 | GIT_REFERENCE_FORMAT_REFSPEC_PATTERN = (1u << 1), |
528a4e24 CMN |
683 | |
684 | /** | |
685 | * Interpret the name as part of a refspec in shorthand form | |
686 | * so the `ONELEVEL` naming rules aren't enforced and 'master' | |
687 | * becomes a valid name. | |
688 | */ | |
e579e0f7 | 689 | GIT_REFERENCE_FORMAT_REFSPEC_SHORTHAND = (1u << 2) |
ac3d33df | 690 | } git_reference_format_t; |
2e0c8816 | 691 | |
692 | /** | |
b90500f0 RB |
693 | * Normalize reference name and check validity. |
694 | * | |
695 | * This will normalize the reference name by removing any leading slash | |
696 | * '/' characters and collapsing runs of adjacent slashes between name | |
697 | * components into a single slash. | |
698 | * | |
699 | * Once normalized, if the reference name is valid, it will be returned in | |
700 | * the user allocated buffer. | |
701 | * | |
3f0e3e16 | 702 | * See `git_reference_symbolic_create()` for rules about valid names. |
80d9d1df | 703 | * |
b90500f0 RB |
704 | * @param buffer_out User allocated buffer to store normalized name |
705 | * @param buffer_size Size of buffer_out | |
706 | * @param name Reference name to be checked. | |
707 | * @param flags Flags to constrain name validation rules - see the | |
ac3d33df | 708 | * GIT_REFERENCE_FORMAT constants above. |
0b170f4d | 709 | * @return 0 on success, GIT_EBUFS if buffer is too small, GIT_EINVALIDSPEC |
80d9d1df | 710 | * or an error code. |
2e0c8816 | 711 | */ |
712 | GIT_EXTERN(int) git_reference_normalize_name( | |
713 | char *buffer_out, | |
714 | size_t buffer_size, | |
715 | const char *name, | |
716 | unsigned int flags); | |
717 | ||
31665948 | 718 | /** |
b90500f0 | 719 | * Recursively peel reference until object of the specified type is found. |
31665948 | 720 | * |
721 | * The retrieved `peeled` object is owned by the repository | |
722 | * and should be closed with the `git_object_free` method. | |
723 | * | |
ac3d33df | 724 | * If you pass `GIT_OBJECT_ANY` as the target type, then the object |
31665948 | 725 | * will be peeled until a non-tag object is met. |
726 | * | |
e1967164 | 727 | * @param out Pointer to the peeled git_object |
31665948 | 728 | * @param ref The reference to be processed |
ac3d33df JK |
729 | * @param type The type of the requested object (GIT_OBJECT_COMMIT, |
730 | * GIT_OBJECT_TAG, GIT_OBJECT_TREE, GIT_OBJECT_BLOB or GIT_OBJECT_ANY). | |
bc05f30c | 731 | * @return 0 on success, GIT_EAMBIGUOUS, GIT_ENOTFOUND or an error code |
31665948 | 732 | */ |
733 | GIT_EXTERN(int) git_reference_peel( | |
734 | git_object **out, | |
ac3d33df JK |
735 | const git_reference *ref, |
736 | git_object_t type); | |
31665948 | 737 | |
77e06d7e | 738 | /** |
739 | * Ensure the reference name is well-formed. | |
740 | * | |
b90500f0 RB |
741 | * Valid reference names must follow one of two patterns: |
742 | * | |
743 | * 1. Top-level names must contain only capital letters and underscores, | |
744 | * and must begin and end with a letter. (e.g. "HEAD", "ORIG_HEAD"). | |
745 | * 2. Names prefixed with "refs/" can be almost anything. You must avoid | |
746 | * the characters '~', '^', ':', '\\', '?', '[', and '*', and the | |
747 | * sequences ".." and "@{" which have special meaning to revparse. | |
77e06d7e | 748 | * |
c25aa7cd | 749 | * @param valid output pointer to set with validity of given reference name |
b90500f0 | 750 | * @param refname name to be checked. |
c25aa7cd | 751 | * @return 0 on success or an error code |
77e06d7e | 752 | */ |
c25aa7cd | 753 | GIT_EXTERN(int) git_reference_name_is_valid(int *valid, const char *refname); |
77e06d7e | 754 | |
4f2eb2b7 CMN |
755 | /** |
756 | * Get the reference's short name | |
757 | * | |
758 | * This will transform the reference name into a name "human-readable" | |
759 | * version. If no shortname is appropriate, it will return the full | |
760 | * name. | |
761 | * | |
762 | * The memory is owned by the reference and must not be freed. | |
763 | * | |
764 | * @param ref a reference | |
765 | * @return the human-readable version of the name | |
766 | */ | |
3b4ba278 | 767 | GIT_EXTERN(const char *) git_reference_shorthand(const git_reference *ref); |
4f2eb2b7 | 768 | |
2f8a8ab2 VM |
769 | /** @} */ |
770 | GIT_END_DECL | |
771 | #endif |