]>
Commit | Line | Data |
---|---|---|
2f8a8ab2 | 1 | /* |
5e0de328 | 2 | * Copyright (C) 2009-2012 the libgit2 contributors |
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" |
2f8a8ab2 VM |
13 | |
14 | /** | |
15 | * @file git2/refs.h | |
16 | * @brief Git reference management routines | |
17 | * @defgroup git_reference Git reference management routines | |
18 | * @ingroup Git | |
19 | * @{ | |
20 | */ | |
21 | GIT_BEGIN_DECL | |
22 | ||
5de079b8 VM |
23 | /** |
24 | * Lookup a reference by its name in a repository. | |
25 | * | |
a46ec457 | 26 | * The generated reference must be freed by the user. |
5de079b8 VM |
27 | * |
28 | * @param reference_out pointer to the looked-up reference | |
29 | * @param repo the repository to look up the reference | |
30 | * @param name the long name for the reference (e.g. HEAD, ref/heads/master, refs/tags/v0.1.0, ...) | |
d9111722 | 31 | * @return GIT_SUCCESS or an error code |
5de079b8 VM |
32 | */ |
33 | GIT_EXTERN(int) git_reference_lookup(git_reference **reference_out, git_repository *repo, const char *name); | |
34 | ||
2f8a8ab2 | 35 | /** |
1d8cc731 | 36 | * Create a new symbolic reference. |
2f8a8ab2 | 37 | * |
1d8cc731 | 38 | * The reference will be created in the repository and written |
39 | * to the disk. | |
2f8a8ab2 | 40 | * |
a46ec457 | 41 | * The generated reference must be freed by the user. |
32054c24 | 42 | * |
d5afc039 VM |
43 | * If `force` is true and there already exists a reference |
44 | * with the same name, it will be overwritten. | |
fa204962 CMN |
45 | * |
46 | * @param ref_out Pointer to the newly created reference | |
47 | * @param repo Repository where that reference will live | |
48 | * @param name The name of the reference | |
49 | * @param target The target of the reference | |
d5afc039 | 50 | * @param force Overwrite existing references |
d9111722 | 51 | * @return GIT_SUCCESS or an error code |
fa204962 | 52 | */ |
d5afc039 | 53 | GIT_EXTERN(int) git_reference_create_symbolic(git_reference **ref_out, git_repository *repo, const char *name, const char *target, int force); |
fa204962 | 54 | |
1d8cc731 | 55 | /** |
56 | * Create a new object id reference. | |
57 | * | |
58 | * The reference will be created in the repository and written | |
59 | * to the disk. | |
60 | * | |
a46ec457 | 61 | * The generated reference must be freed by the user. |
32054c24 | 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 id The object id pointed to by the reference. | |
d5afc039 | 70 | * @param force Overwrite existing references |
d9111722 | 71 | * @return GIT_SUCCESS or an error code |
fa204962 | 72 | */ |
d5afc039 | 73 | GIT_EXTERN(int) git_reference_create_oid(git_reference **ref_out, git_repository *repo, const char *name, const git_oid *id, int force); |
fa204962 | 74 | |
2f8a8ab2 VM |
75 | /** |
76 | * Get the OID pointed to by a reference. | |
932d1baf | 77 | * |
2f8a8ab2 VM |
78 | * Only available if the reference is direct (i.e. not symbolic) |
79 | * | |
80 | * @param ref The reference | |
81 | * @return a pointer to the oid if available, NULL otherwise | |
82 | */ | |
83 | GIT_EXTERN(const git_oid *) git_reference_oid(git_reference *ref); | |
84 | ||
85 | /** | |
86 | * Get full name to the reference pointed by this reference | |
932d1baf | 87 | * |
2f8a8ab2 VM |
88 | * Only available if the reference is symbolic |
89 | * | |
90 | * @param ref The reference | |
91 | * @return a pointer to the name if available, NULL otherwise | |
92 | */ | |
93 | GIT_EXTERN(const char *) git_reference_target(git_reference *ref); | |
94 | ||
95 | /** | |
96 | * Get the type of a reference | |
97 | * | |
98 | * Either direct (GIT_REF_OID) or symbolic (GIT_REF_SYMBOLIC) | |
99 | * | |
100 | * @param ref The reference | |
101 | * @return the type | |
102 | */ | |
103 | GIT_EXTERN(git_rtype) git_reference_type(git_reference *ref); | |
104 | ||
105 | /** | |
106 | * Get the full name of a reference | |
107 | * | |
108 | * @param ref The reference | |
109 | * @return the full name for the ref | |
110 | */ | |
111 | GIT_EXTERN(const char *) git_reference_name(git_reference *ref); | |
112 | ||
113 | /** | |
932d1baf | 114 | * Resolve a symbolic reference |
2f8a8ab2 VM |
115 | * |
116 | * Thie method iteratively peels a symbolic reference | |
117 | * until it resolves to a direct reference to an OID. | |
118 | * | |
d4a0b124 VM |
119 | * The peeled reference is returned in the `resolved_ref` |
120 | * argument, and must be freed manually once it's no longer | |
121 | * needed. | |
122 | * | |
2f8a8ab2 | 123 | * If a direct reference is passed as an argument, |
d4a0b124 VM |
124 | * a copy of that reference is returned. This copy must |
125 | * be manually freed too. | |
2f8a8ab2 VM |
126 | * |
127 | * @param resolved_ref Pointer to the peeled reference | |
128 | * @param ref The reference | |
d9111722 | 129 | * @return GIT_SUCCESS or an error code |
2f8a8ab2 VM |
130 | */ |
131 | GIT_EXTERN(int) git_reference_resolve(git_reference **resolved_ref, git_reference *ref); | |
132 | ||
2f8a8ab2 VM |
133 | /** |
134 | * Get the repository where a reference resides | |
135 | * | |
136 | * @param ref The reference | |
137 | * @return a pointer to the repo | |
138 | */ | |
139 | GIT_EXTERN(git_repository *) git_reference_owner(git_reference *ref); | |
140 | ||
2f8a8ab2 | 141 | /** |
32054c24 | 142 | * Set the symbolic target of a reference. |
2f8a8ab2 | 143 | * |
32054c24 VM |
144 | * The reference must be a symbolic reference, otherwise |
145 | * this method will fail. | |
2f8a8ab2 | 146 | * |
32054c24 VM |
147 | * The reference will be automatically updated in |
148 | * memory and on disk. | |
2f8a8ab2 VM |
149 | * |
150 | * @param ref The reference | |
151 | * @param target The new target for the reference | |
d9111722 | 152 | * @return GIT_SUCCESS or an error code |
2f8a8ab2 | 153 | */ |
1d8cc731 | 154 | GIT_EXTERN(int) git_reference_set_target(git_reference *ref, const char *target); |
2f8a8ab2 VM |
155 | |
156 | /** | |
157 | * Set the OID target of a reference. | |
158 | * | |
32054c24 VM |
159 | * The reference must be a direct reference, otherwise |
160 | * this method will fail. | |
2f8a8ab2 | 161 | * |
32054c24 VM |
162 | * The reference will be automatically updated in |
163 | * memory and on disk. | |
2f8a8ab2 VM |
164 | * |
165 | * @param ref The reference | |
d144c569 | 166 | * @param id The new target OID for the reference |
d9111722 | 167 | * @return GIT_SUCCESS or an error code |
2f8a8ab2 | 168 | */ |
1d8cc731 | 169 | GIT_EXTERN(int) git_reference_set_oid(git_reference *ref, const git_oid *id); |
2f8a8ab2 | 170 | |
32054c24 VM |
171 | /** |
172 | * Rename an existing reference | |
173 | * | |
174 | * This method works for both direct and symbolic references. | |
175 | * The new name will be checked for validity and may be | |
176 | * modified into a normalized form. | |
177 | * | |
d4a0b124 | 178 | * The given git_reference will be updated in place. |
a46ec457 MS |
179 | * |
180 | * The reference will be immediately renamed in-memory | |
32054c24 VM |
181 | * and on disk. |
182 | * | |
d4a0b124 VM |
183 | * If the `force` flag is not enabled, and there's already |
184 | * a reference with the given name, the renaming will fail. | |
185 | * | |
a5cd086d MS |
186 | * IMPORTANT: |
187 | * The user needs to write a proper reflog entry if the | |
188 | * reflog is enabled for the repository. We only rename | |
189 | * the reflog if it exists. | |
190 | * | |
d4a0b124 VM |
191 | * @param ref The reference to rename |
192 | * @param new_name The new name for the reference | |
193 | * @param force Overwrite an existing reference | |
194 | * @return GIT_SUCCESS or an error code | |
195 | * | |
32054c24 | 196 | */ |
7376ad99 | 197 | GIT_EXTERN(int) git_reference_rename(git_reference *ref, const char *new_name, int force); |
fa204962 | 198 | |
32054c24 VM |
199 | /** |
200 | * Delete an existing reference | |
201 | * | |
202 | * This method works for both direct and symbolic references. | |
203 | * | |
204 | * The reference will be immediately removed on disk and from | |
205 | * memory. The given reference pointer will no longer be valid. | |
206 | * | |
d4a0b124 VM |
207 | * @param ref The reference to remove |
208 | * @return GIT_SUCCESS or an error code | |
32054c24 VM |
209 | */ |
210 | GIT_EXTERN(int) git_reference_delete(git_reference *ref); | |
211 | ||
87d3acf4 VM |
212 | /** |
213 | * Pack all the loose references in the repository | |
214 | * | |
215 | * This method will load into the cache all the loose | |
932d1baf | 216 | * references on the repository and update the |
87d3acf4 VM |
217 | * `packed-refs` file with them. |
218 | * | |
219 | * Once the `packed-refs` file has been written properly, | |
220 | * the loose references will be removed from disk. | |
221 | * | |
87d3acf4 | 222 | * @param repo Repository where the loose refs will be packed |
d9111722 | 223 | * @return GIT_SUCCESS or an error code |
87d3acf4 VM |
224 | */ |
225 | GIT_EXTERN(int) git_reference_packall(git_repository *repo); | |
226 | ||
00571828 VM |
227 | /** |
228 | * Fill a list with all the references that can be found | |
229 | * in a repository. | |
230 | * | |
231 | * The listed references may be filtered by type, or using | |
232 | * a bitwise OR of several types. Use the magic value | |
233 | * `GIT_REF_LISTALL` to obtain all references, including | |
234 | * packed ones. | |
235 | * | |
236 | * The string array will be filled with the names of all | |
237 | * references; these values are owned by the user and | |
238 | * should be free'd manually when no longer needed, using | |
239 | * `git_strarray_free`. | |
240 | * | |
241 | * @param array Pointer to a git_strarray structure where | |
242 | * the reference names will be stored | |
243 | * @param repo Repository where to find the refs | |
244 | * @param list_flags Filtering flags for the reference | |
245 | * listing. | |
d9111722 | 246 | * @return GIT_SUCCESS or an error code |
00571828 VM |
247 | */ |
248 | GIT_EXTERN(int) git_reference_listall(git_strarray *array, git_repository *repo, unsigned int list_flags); | |
249 | ||
09e8de0f VM |
250 | |
251 | /** | |
43521d06 | 252 | * Perform an operation on each reference in the repository |
09e8de0f | 253 | * |
43521d06 | 254 | * The processed references may be filtered by type, or using |
09e8de0f VM |
255 | * a bitwise OR of several types. Use the magic value |
256 | * `GIT_REF_LISTALL` to obtain all references, including | |
257 | * packed ones. | |
258 | * | |
259 | * The `callback` function will be called for each of the references | |
260 | * in the repository, and will receive the name of the reference and | |
261 | * the `payload` value passed to this method. | |
262 | * | |
263 | * @param repo Repository where to find the refs | |
264 | * @param list_flags Filtering flags for the reference | |
265 | * listing. | |
266 | * @param callback Function which will be called for every listed ref | |
267 | * @param payload Additional data to pass to the callback | |
d9111722 | 268 | * @return GIT_SUCCESS or an error code |
09e8de0f | 269 | */ |
43521d06 | 270 | GIT_EXTERN(int) git_reference_foreach(git_repository *repo, unsigned int list_flags, int (*callback)(const char *, void *), void *payload); |
09e8de0f | 271 | |
a46ec457 | 272 | /** |
d4a0b124 | 273 | * Check if a reference has been loaded from a packfile |
a46ec457 | 274 | * |
d4a0b124 | 275 | * @param ref A git reference |
a46ec457 MS |
276 | * @return 0 in case it's not packed; 1 otherwise |
277 | */ | |
278 | GIT_EXTERN(int) git_reference_is_packed(git_reference *ref); | |
279 | ||
d4a0b124 VM |
280 | /** |
281 | * Reload a reference from disk | |
282 | * | |
283 | * Reference pointers may become outdated if the Git | |
284 | * repository is accessed simultaneously by other clients | |
285 | * whilt the library is open. | |
286 | * | |
287 | * This method forces a reload of the reference from disk, | |
288 | * to ensure that the provided information is still | |
289 | * reliable. | |
290 | * | |
291 | * If the reload fails (e.g. the reference no longer exists | |
292 | * on disk, or has become corrupted), an error code will be | |
293 | * returned and the reference pointer will be invalidated. | |
294 | * | |
295 | * @param ref The reference to reload | |
296 | * @return GIT_SUCCESS on success, or an error code | |
297 | */ | |
298 | GIT_EXTERN(int) git_reference_reload(git_reference *ref); | |
299 | ||
a46ec457 MS |
300 | /** |
301 | * Free the given reference | |
302 | * | |
303 | * @param ref git_reference | |
304 | */ | |
305 | GIT_EXTERN(void) git_reference_free(git_reference *ref); | |
306 | ||
2f8a8ab2 VM |
307 | /** @} */ |
308 | GIT_END_DECL | |
309 | #endif |