]>
Commit | Line | Data |
---|---|---|
f5918330 | 1 | /* |
359fc2d2 | 2 | * Copyright (C) the libgit2 contributors. All rights reserved. |
f5918330 | 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. | |
f5918330 | 6 | */ |
225fe215 VM |
7 | #ifndef INCLUDE_git_tree_h__ |
8 | #define INCLUDE_git_tree_h__ | |
9 | ||
10 | #include "common.h" | |
d12299fe | 11 | #include "types.h" |
225fe215 | 12 | #include "oid.h" |
5de079b8 | 13 | #include "object.h" |
225fe215 VM |
14 | |
15 | /** | |
f5918330 | 16 | * @file git2/tree.h |
225fe215 VM |
17 | * @brief Git tree parsing, loading routines |
18 | * @defgroup git_tree Git tree parsing, loading routines | |
19 | * @ingroup Git | |
20 | * @{ | |
21 | */ | |
22 | GIT_BEGIN_DECL | |
23 | ||
225fe215 | 24 | /** |
3315782c | 25 | * Lookup a tree object from the repository. |
225fe215 | 26 | * |
e120123e RB |
27 | * @param out Pointer to the looked up tree |
28 | * @param repo The repo to use when locating the tree. | |
29 | * @param id Identity of the tree to locate. | |
e172cf08 | 30 | * @return 0 or an error code |
225fe215 | 31 | */ |
d7761102 RB |
32 | GIT_EXTERN(int) git_tree_lookup( |
33 | git_tree **out, git_repository *repo, const git_oid *id); | |
d8603ed9 | 34 | |
790c6c95 MP |
35 | /** |
36 | * Lookup a tree object from the repository, | |
37 | * given a prefix of its identifier (short id). | |
38 | * | |
39 | * @see git_object_lookup_prefix | |
40 | * | |
e1967164 | 41 | * @param out pointer to the looked up tree |
790c6c95 MP |
42 | * @param repo the repo to use when locating the tree. |
43 | * @param id identity of the tree to locate. | |
44 | * @param len the length of the short identifier | |
e172cf08 | 45 | * @return 0 or an error code |
790c6c95 | 46 | */ |
d7761102 | 47 | GIT_EXTERN(int) git_tree_lookup_prefix( |
e120123e | 48 | git_tree **out, |
0e2fcca8 VM |
49 | git_repository *repo, |
50 | const git_oid *id, | |
d7761102 | 51 | size_t len); |
790c6c95 | 52 | |
b0b83135 CMN |
53 | /** |
54 | * Close an open tree | |
55 | * | |
e120123e | 56 | * You can no longer use the git_tree pointer after this call. |
b0b83135 | 57 | * |
e120123e RB |
58 | * IMPORTANT: You MUST call this method when you stop using a tree to |
59 | * release memory. Failure to do so will cause a memory leak. | |
b0b83135 | 60 | * |
e120123e | 61 | * @param tree The tree to close |
b0b83135 | 62 | */ |
d7761102 | 63 | GIT_EXTERN(void) git_tree_free(git_tree *tree); |
b0b83135 | 64 | |
225fe215 VM |
65 | /** |
66 | * Get the id of a tree. | |
72a3fe42 | 67 | * |
225fe215 VM |
68 | * @param tree a previously loaded tree. |
69 | * @return object identity for the tree. | |
70 | */ | |
0d64bef9 | 71 | GIT_EXTERN(const git_oid *) git_tree_id(const git_tree *tree); |
225fe215 | 72 | |
9950d27a RB |
73 | /** |
74 | * Get the repository that contains the tree. | |
75 | * | |
76 | * @param tree A previously loaded tree. | |
77 | * @return Repository that contains this tree. | |
78 | */ | |
79 | GIT_EXTERN(git_repository *) git_tree_owner(const git_tree *tree); | |
80 | ||
003c2690 VM |
81 | /** |
82 | * Get the number of entries listed in a tree | |
72a3fe42 | 83 | * |
003c2690 VM |
84 | * @param tree a previously loaded tree. |
85 | * @return the number of entries in the tree | |
86 | */ | |
e120123e | 87 | GIT_EXTERN(size_t) git_tree_entrycount(const git_tree *tree); |
003c2690 VM |
88 | |
89 | /** | |
90 | * Lookup a tree entry by its filename | |
72a3fe42 | 91 | * |
e120123e RB |
92 | * This returns a git_tree_entry that is owned by the git_tree. You don't |
93 | * have to free it, but you must not use it after the git_tree is released. | |
94 | * | |
003c2690 VM |
95 | * @param tree a previously loaded tree. |
96 | * @param filename the filename of the desired entry | |
97 | * @return the tree entry; NULL if not found | |
98 | */ | |
e120123e | 99 | GIT_EXTERN(const git_tree_entry *) git_tree_entry_byname( |
58206c9a | 100 | const git_tree *tree, const char *filename); |
003c2690 VM |
101 | |
102 | /** | |
103 | * Lookup a tree entry by its position in the tree | |
72a3fe42 | 104 | * |
e120123e RB |
105 | * This returns a git_tree_entry that is owned by the git_tree. You don't |
106 | * have to free it, but you must not use it after the git_tree is released. | |
107 | * | |
003c2690 VM |
108 | * @param tree a previously loaded tree. |
109 | * @param idx the position in the entry list | |
110 | * @return the tree entry; NULL if not found | |
111 | */ | |
e120123e | 112 | GIT_EXTERN(const git_tree_entry *) git_tree_entry_byindex( |
58206c9a | 113 | const git_tree *tree, size_t idx); |
003c2690 | 114 | |
2031760c RB |
115 | /** |
116 | * Lookup a tree entry by SHA value. | |
117 | * | |
e120123e RB |
118 | * This returns a git_tree_entry that is owned by the git_tree. You don't |
119 | * have to free it, but you must not use it after the git_tree is released. | |
120 | * | |
2031760c RB |
121 | * Warning: this must examine every entry in the tree, so it is not fast. |
122 | * | |
123 | * @param tree a previously loaded tree. | |
f000ee4e | 124 | * @param id the sha being looked for |
2031760c RB |
125 | * @return the tree entry; NULL if not found |
126 | */ | |
f000ee4e CMN |
127 | GIT_EXTERN(const git_tree_entry *) git_tree_entry_byid( |
128 | const git_tree *tree, const git_oid *id); | |
2031760c | 129 | |
003c2690 | 130 | /** |
e120123e RB |
131 | * Retrieve a tree entry contained in a tree or in any of its subtrees, |
132 | * given its relative path. | |
72a3fe42 | 133 | * |
e120123e RB |
134 | * Unlike the other lookup functions, the returned tree entry is owned by |
135 | * the user and must be freed explicitly with `git_tree_entry_free()`. | |
136 | * | |
137 | * @param out Pointer where to store the tree entry | |
138 | * @param root Previously loaded tree which is the root of the relative path | |
e1967164 | 139 | * @param path Path to the contained entry |
e120123e | 140 | * @return 0 on success; GIT_ENOTFOUND if the path does not exist |
003c2690 | 141 | */ |
e120123e RB |
142 | GIT_EXTERN(int) git_tree_entry_bypath( |
143 | git_tree_entry **out, | |
58206c9a | 144 | const git_tree *root, |
e120123e RB |
145 | const char *path); |
146 | ||
147 | /** | |
148 | * Duplicate a tree entry | |
149 | * | |
150 | * Create a copy of a tree entry. The returned copy is owned by the user, | |
151 | * and must be freed explicitly with `git_tree_entry_free()`. | |
152 | * | |
529f342a | 153 | * @param dest pointer where to store the copy |
31b0cb51 | 154 | * @param source tree entry to duplicate |
529f342a | 155 | * @return 0 or an error code |
e120123e | 156 | */ |
529f342a | 157 | GIT_EXTERN(int) git_tree_entry_dup(git_tree_entry **dest, const git_tree_entry *source); |
e120123e RB |
158 | |
159 | /** | |
160 | * Free a user-owned tree entry | |
161 | * | |
162 | * IMPORTANT: This function is only needed for tree entries owned by the | |
163 | * user, such as the ones returned by `git_tree_entry_dup()` or | |
164 | * `git_tree_entry_bypath()`. | |
165 | * | |
166 | * @param entry The entry to free | |
167 | */ | |
168 | GIT_EXTERN(void) git_tree_entry_free(git_tree_entry *entry); | |
003c2690 VM |
169 | |
170 | /** | |
171 | * Get the filename of a tree entry | |
72a3fe42 | 172 | * |
003c2690 VM |
173 | * @param entry a tree entry |
174 | * @return the name of the file | |
175 | */ | |
0ad6efa1 | 176 | GIT_EXTERN(const char *) git_tree_entry_name(const git_tree_entry *entry); |
003c2690 VM |
177 | |
178 | /** | |
179 | * Get the id of the object pointed by the entry | |
72a3fe42 | 180 | * |
003c2690 VM |
181 | * @param entry a tree entry |
182 | * @return the oid of the object | |
183 | */ | |
0ad6efa1 | 184 | GIT_EXTERN(const git_oid *) git_tree_entry_id(const git_tree_entry *entry); |
003c2690 | 185 | |
ff9a4c13 RG |
186 | /** |
187 | * Get the type of the object pointed by the entry | |
188 | * | |
189 | * @param entry a tree entry | |
190 | * @return the type of the pointed object | |
191 | */ | |
192 | GIT_EXTERN(git_otype) git_tree_entry_type(const git_tree_entry *entry); | |
193 | ||
e120123e RB |
194 | /** |
195 | * Get the UNIX file attributes of a tree entry | |
196 | * | |
197 | * @param entry a tree entry | |
198 | * @return filemode as an integer | |
199 | */ | |
200 | GIT_EXTERN(git_filemode_t) git_tree_entry_filemode(const git_tree_entry *entry); | |
201 | ||
13f670a5 CMN |
202 | /** |
203 | * Get the raw UNIX file attributes of a tree entry | |
204 | * | |
205 | * This function does not perform any normalization and is only useful | |
206 | * if you need to be able to recreate the original tree object. | |
207 | * | |
208 | * @param entry a tree entry | |
209 | * @return filemode as an integer | |
210 | */ | |
211 | ||
212 | GIT_EXTERN(git_filemode_t) git_tree_entry_filemode_raw(const git_tree_entry *entry); | |
98527b5b RB |
213 | /** |
214 | * Compare two tree entries | |
215 | * | |
216 | * @param e1 first tree entry | |
217 | * @param e2 second tree entry | |
218 | * @return <0 if e1 is before e2, 0 if e1 == e2, >0 if e1 is after e2 | |
219 | */ | |
220 | GIT_EXTERN(int) git_tree_entry_cmp(const git_tree_entry *e1, const git_tree_entry *e2); | |
221 | ||
003c2690 | 222 | /** |
51b0397a | 223 | * Convert a tree entry to the git_object it points to. |
1795f879 | 224 | * |
e120123e RB |
225 | * You must call `git_object_free()` on the object when you are done with it. |
226 | * | |
e1967164 | 227 | * @param object_out pointer to the converted object |
72a3fe42 | 228 | * @param repo repository where to lookup the pointed object |
003c2690 | 229 | * @param entry a tree entry |
e172cf08 | 230 | * @return 0 or an error code |
003c2690 | 231 | */ |
0e2fcca8 VM |
232 | GIT_EXTERN(int) git_tree_entry_to_object( |
233 | git_object **object_out, | |
234 | git_repository *repo, | |
235 | const git_tree_entry *entry); | |
003c2690 | 236 | |
0ad6efa1 VM |
237 | /** |
238 | * Create a new tree builder. | |
239 | * | |
e120123e RB |
240 | * The tree builder can be used to create or modify trees in memory and |
241 | * write them as tree objects to the database. | |
0ad6efa1 | 242 | * |
e120123e RB |
243 | * If the `source` parameter is not NULL, the tree builder will be |
244 | * initialized with the entries of the given tree. | |
932d1baf | 245 | * |
e120123e RB |
246 | * If the `source` parameter is NULL, the tree builder will start with no |
247 | * entries and will have to be filled manually. | |
0ad6efa1 | 248 | * |
e120123e | 249 | * @param out Pointer where to store the tree builder |
0ad6efa1 | 250 | * @param source Source tree to initialize the builder (optional) |
d73c94b2 | 251 | * @return 0 on success; error code otherwise |
0ad6efa1 | 252 | */ |
e120123e RB |
253 | GIT_EXTERN(int) git_treebuilder_create( |
254 | git_treebuilder **out, const git_tree *source); | |
0ad6efa1 VM |
255 | |
256 | /** | |
257 | * Clear all the entires in the builder | |
258 | * | |
259 | * @param bld Builder to clear | |
260 | */ | |
261 | GIT_EXTERN(void) git_treebuilder_clear(git_treebuilder *bld); | |
262 | ||
5fb98206 JW |
263 | /** |
264 | * Get the number of entries listed in a treebuilder | |
265 | * | |
e1967164 | 266 | * @param bld a previously loaded treebuilder. |
5fb98206 JW |
267 | * @return the number of entries in the treebuilder |
268 | */ | |
269 | GIT_EXTERN(unsigned int) git_treebuilder_entrycount(git_treebuilder *bld); | |
270 | ||
0ad6efa1 VM |
271 | /** |
272 | * Free a tree builder | |
273 | * | |
274 | * This will clear all the entries and free to builder. | |
275 | * Failing to free the builder after you're done using it | |
276 | * will result in a memory leak | |
277 | * | |
278 | * @param bld Builder to free | |
279 | */ | |
280 | GIT_EXTERN(void) git_treebuilder_free(git_treebuilder *bld); | |
281 | ||
282 | /** | |
283 | * Get an entry from the builder from its filename | |
284 | * | |
285 | * The returned entry is owned by the builder and should | |
286 | * not be freed manually. | |
287 | * | |
288 | * @param bld Tree builder | |
289 | * @param filename Name of the entry | |
290 | * @return pointer to the entry; NULL if not found | |
291 | */ | |
e120123e RB |
292 | GIT_EXTERN(const git_tree_entry *) git_treebuilder_get( |
293 | git_treebuilder *bld, const char *filename); | |
0ad6efa1 VM |
294 | |
295 | /** | |
296 | * Add or update an entry to the builder | |
297 | * | |
298 | * Insert a new entry for `filename` in the builder with the | |
299 | * given attributes. | |
300 | * | |
e120123e | 301 | * If an entry named `filename` already exists, its attributes |
0ad6efa1 VM |
302 | * will be updated with the given ones. |
303 | * | |
e120123e RB |
304 | * The optional pointer `out` can be used to retrieve a pointer to |
305 | * the newly created/updated entry. Pass NULL if you do not need it. | |
0ad6efa1 | 306 | * |
66439b0b | 307 | * No attempt is being made to ensure that the provided oid points |
308 | * to an existing git object in the object database, nor that the | |
309 | * attributes make sense regarding the type of the pointed at object. | |
310 | * | |
e120123e | 311 | * @param out Pointer to store the entry (optional) |
0ad6efa1 VM |
312 | * @param bld Tree builder |
313 | * @param filename Filename of the entry | |
314 | * @param id SHA1 oid of the entry | |
a7dbac0b | 315 | * @param filemode Folder attributes of the entry. This parameter must |
66439b0b | 316 | * be valued with one of the following entries: 0040000, 0100644, |
317 | * 0100755, 0120000 or 0160000. | |
e172cf08 | 318 | * @return 0 or an error code |
0ad6efa1 | 319 | */ |
0e2fcca8 | 320 | GIT_EXTERN(int) git_treebuilder_insert( |
e120123e | 321 | const git_tree_entry **out, |
0e2fcca8 VM |
322 | git_treebuilder *bld, |
323 | const char *filename, | |
324 | const git_oid *id, | |
a7dbac0b | 325 | git_filemode_t filemode); |
0ad6efa1 VM |
326 | |
327 | /** | |
328 | * Remove an entry from the builder by its filename | |
329 | * | |
330 | * @param bld Tree builder | |
331 | * @param filename Filename of the entry to remove | |
332 | */ | |
e120123e RB |
333 | GIT_EXTERN(int) git_treebuilder_remove( |
334 | git_treebuilder *bld, const char *filename); | |
335 | ||
452c7de6 RB |
336 | /** |
337 | * Callback for git_treebuilder_filter | |
338 | * | |
339 | * The return value is treated as a boolean, with zero indicating that the | |
340 | * entry should be left alone and any non-zero value meaning that the | |
341 | * entry should be removed from the treebuilder list (i.e. filtered out). | |
342 | */ | |
e120123e RB |
343 | typedef int (*git_treebuilder_filter_cb)( |
344 | const git_tree_entry *entry, void *payload); | |
0ad6efa1 VM |
345 | |
346 | /** | |
452c7de6 | 347 | * Selectively remove entries in the tree |
0ad6efa1 | 348 | * |
e120123e RB |
349 | * The `filter` callback will be called for each entry in the tree with a |
350 | * pointer to the entry and the provided `payload`; if the callback returns | |
351 | * non-zero, the entry will be filtered (removed from the builder). | |
0ad6efa1 VM |
352 | * |
353 | * @param bld Tree builder | |
354 | * @param filter Callback to filter entries | |
452c7de6 | 355 | * @param payload Extra data to pass to filter callback |
0ad6efa1 | 356 | */ |
4d3f1f97 | 357 | GIT_EXTERN(int) git_treebuilder_filter( |
0e2fcca8 | 358 | git_treebuilder *bld, |
e120123e | 359 | git_treebuilder_filter_cb filter, |
0e2fcca8 | 360 | void *payload); |
0ad6efa1 VM |
361 | |
362 | /** | |
363 | * Write the contents of the tree builder as a tree object | |
364 | * | |
e120123e RB |
365 | * The tree builder will be written to the given `repo`, and its |
366 | * identifying SHA1 hash will be stored in the `id` pointer. | |
0ad6efa1 | 367 | * |
e120123e RB |
368 | * @param id Pointer to store the OID of the newly written tree |
369 | * @param repo Repository in which to store the object | |
0ad6efa1 | 370 | * @param bld Tree builder to write |
e172cf08 | 371 | * @return 0 or an error code |
0ad6efa1 | 372 | */ |
e120123e RB |
373 | GIT_EXTERN(int) git_treebuilder_write( |
374 | git_oid *id, git_repository *repo, git_treebuilder *bld); | |
0ad6efa1 | 375 | |
da37654d VM |
376 | |
377 | /** Callback for the tree traversal method */ | |
e120123e RB |
378 | typedef int (*git_treewalk_cb)( |
379 | const char *root, const git_tree_entry *entry, void *payload); | |
da37654d VM |
380 | |
381 | /** Tree traversal modes */ | |
e120123e | 382 | typedef enum { |
da37654d VM |
383 | GIT_TREEWALK_PRE = 0, /* Pre-order */ |
384 | GIT_TREEWALK_POST = 1, /* Post-order */ | |
e120123e | 385 | } git_treewalk_mode; |
da37654d VM |
386 | |
387 | /** | |
16248ee2 | 388 | * Traverse the entries in a tree and its subtrees in post or pre order. |
da37654d | 389 | * |
16248ee2 RB |
390 | * The entries will be traversed in the specified order, children subtrees |
391 | * will be automatically loaded as required, and the `callback` will be | |
392 | * called once per entry with the current (relative) root for the entry and | |
393 | * the entry data itself. | |
da37654d | 394 | * |
a6bf1687 | 395 | * If the callback returns a positive value, the passed entry will be |
16248ee2 | 396 | * skipped on the traversal (in pre mode). A negative value stops the walk. |
da37654d VM |
397 | * |
398 | * @param tree The tree to walk | |
da37654d | 399 | * @param mode Traversal mode (pre or post-order) |
e120123e | 400 | * @param callback Function to call on each tree entry |
2744806f | 401 | * @param payload Opaque pointer to be passed on each callback |
e172cf08 | 402 | * @return 0 or an error code |
da37654d | 403 | */ |
e120123e | 404 | GIT_EXTERN(int) git_tree_walk( |
f45d51ff | 405 | const git_tree *tree, |
e120123e RB |
406 | git_treewalk_mode mode, |
407 | git_treewalk_cb callback, | |
408 | void *payload); | |
da37654d | 409 | |
3a437590 RB |
410 | /** @} */ |
411 | ||
225fe215 VM |
412 | GIT_END_DECL |
413 | #endif |