]>
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 | */ | |
ac3d33df | 192 | GIT_EXTERN(git_object_t) git_tree_entry_type(const git_tree_entry *entry); |
ff9a4c13 | 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 |
dce7b1a4 | 250 | * @param repo Repository in which to store the object |
0ad6efa1 | 251 | * @param source Source tree to initialize the builder (optional) |
d73c94b2 | 252 | * @return 0 on success; error code otherwise |
0ad6efa1 | 253 | */ |
208a2c8a | 254 | GIT_EXTERN(int) git_treebuilder_new( |
dce7b1a4 | 255 | git_treebuilder **out, git_repository *repo, const git_tree *source); |
0ad6efa1 VM |
256 | |
257 | /** | |
258 | * Clear all the entires in the builder | |
259 | * | |
260 | * @param bld Builder to clear | |
22a2d3d5 | 261 | * @return 0 on success; error code otherwise |
0ad6efa1 | 262 | */ |
22a2d3d5 | 263 | GIT_EXTERN(int) git_treebuilder_clear(git_treebuilder *bld); |
0ad6efa1 | 264 | |
5fb98206 JW |
265 | /** |
266 | * Get the number of entries listed in a treebuilder | |
267 | * | |
e1967164 | 268 | * @param bld a previously loaded treebuilder. |
5fb98206 JW |
269 | * @return the number of entries in the treebuilder |
270 | */ | |
22a2d3d5 | 271 | GIT_EXTERN(size_t) git_treebuilder_entrycount(git_treebuilder *bld); |
5fb98206 | 272 | |
0ad6efa1 VM |
273 | /** |
274 | * Free a tree builder | |
275 | * | |
276 | * This will clear all the entries and free to builder. | |
277 | * Failing to free the builder after you're done using it | |
278 | * will result in a memory leak | |
279 | * | |
280 | * @param bld Builder to free | |
281 | */ | |
282 | GIT_EXTERN(void) git_treebuilder_free(git_treebuilder *bld); | |
283 | ||
284 | /** | |
285 | * Get an entry from the builder from its filename | |
286 | * | |
287 | * The returned entry is owned by the builder and should | |
288 | * not be freed manually. | |
289 | * | |
290 | * @param bld Tree builder | |
291 | * @param filename Name of the entry | |
292 | * @return pointer to the entry; NULL if not found | |
293 | */ | |
e120123e RB |
294 | GIT_EXTERN(const git_tree_entry *) git_treebuilder_get( |
295 | git_treebuilder *bld, const char *filename); | |
0ad6efa1 VM |
296 | |
297 | /** | |
298 | * Add or update an entry to the builder | |
299 | * | |
300 | * Insert a new entry for `filename` in the builder with the | |
301 | * given attributes. | |
302 | * | |
e120123e | 303 | * If an entry named `filename` already exists, its attributes |
0ad6efa1 VM |
304 | * will be updated with the given ones. |
305 | * | |
978fbb4c CMN |
306 | * The optional pointer `out` can be used to retrieve a pointer to the |
307 | * newly created/updated entry. Pass NULL if you do not need it. The | |
308 | * pointer may not be valid past the next operation in this | |
309 | * builder. Duplicate the entry if you want to keep it. | |
0ad6efa1 | 310 | * |
eae0bfdc PP |
311 | * By default the entry that you are inserting will be checked for |
312 | * validity; that it exists in the object database and is of the | |
313 | * correct type. If you do not want this behavior, set the | |
314 | * `GIT_OPT_ENABLE_STRICT_OBJECT_CREATION` library option to false. | |
66439b0b | 315 | * |
e120123e | 316 | * @param out Pointer to store the entry (optional) |
0ad6efa1 VM |
317 | * @param bld Tree builder |
318 | * @param filename Filename of the entry | |
319 | * @param id SHA1 oid of the entry | |
a7dbac0b | 320 | * @param filemode Folder attributes of the entry. This parameter must |
66439b0b | 321 | * be valued with one of the following entries: 0040000, 0100644, |
322 | * 0100755, 0120000 or 0160000. | |
e172cf08 | 323 | * @return 0 or an error code |
0ad6efa1 | 324 | */ |
0e2fcca8 | 325 | GIT_EXTERN(int) git_treebuilder_insert( |
e120123e | 326 | const git_tree_entry **out, |
0e2fcca8 VM |
327 | git_treebuilder *bld, |
328 | const char *filename, | |
329 | const git_oid *id, | |
a7dbac0b | 330 | git_filemode_t filemode); |
0ad6efa1 VM |
331 | |
332 | /** | |
333 | * Remove an entry from the builder by its filename | |
334 | * | |
335 | * @param bld Tree builder | |
336 | * @param filename Filename of the entry to remove | |
c25aa7cd | 337 | * @return 0 or an error code |
0ad6efa1 | 338 | */ |
e120123e RB |
339 | GIT_EXTERN(int) git_treebuilder_remove( |
340 | git_treebuilder *bld, const char *filename); | |
341 | ||
452c7de6 RB |
342 | /** |
343 | * Callback for git_treebuilder_filter | |
344 | * | |
345 | * The return value is treated as a boolean, with zero indicating that the | |
346 | * entry should be left alone and any non-zero value meaning that the | |
347 | * entry should be removed from the treebuilder list (i.e. filtered out). | |
348 | */ | |
ac3d33df | 349 | typedef int GIT_CALLBACK(git_treebuilder_filter_cb)( |
e120123e | 350 | const git_tree_entry *entry, void *payload); |
0ad6efa1 VM |
351 | |
352 | /** | |
452c7de6 | 353 | * Selectively remove entries in the tree |
0ad6efa1 | 354 | * |
e120123e RB |
355 | * The `filter` callback will be called for each entry in the tree with a |
356 | * pointer to the entry and the provided `payload`; if the callback returns | |
357 | * non-zero, the entry will be filtered (removed from the builder). | |
0ad6efa1 VM |
358 | * |
359 | * @param bld Tree builder | |
360 | * @param filter Callback to filter entries | |
452c7de6 | 361 | * @param payload Extra data to pass to filter callback |
22a2d3d5 | 362 | * @return 0 on success, non-zero callback return value, or error code |
0ad6efa1 | 363 | */ |
22a2d3d5 | 364 | GIT_EXTERN(int) git_treebuilder_filter( |
0e2fcca8 | 365 | git_treebuilder *bld, |
e120123e | 366 | git_treebuilder_filter_cb filter, |
0e2fcca8 | 367 | void *payload); |
0ad6efa1 VM |
368 | |
369 | /** | |
370 | * Write the contents of the tree builder as a tree object | |
371 | * | |
e120123e RB |
372 | * The tree builder will be written to the given `repo`, and its |
373 | * identifying SHA1 hash will be stored in the `id` pointer. | |
0ad6efa1 | 374 | * |
e120123e | 375 | * @param id Pointer to store the OID of the newly written tree |
0ad6efa1 | 376 | * @param bld Tree builder to write |
e172cf08 | 377 | * @return 0 or an error code |
0ad6efa1 | 378 | */ |
e120123e | 379 | GIT_EXTERN(int) git_treebuilder_write( |
dce7b1a4 | 380 | git_oid *id, git_treebuilder *bld); |
0ad6efa1 | 381 | |
da37654d | 382 | /** Callback for the tree traversal method */ |
ac3d33df | 383 | typedef int GIT_CALLBACK(git_treewalk_cb)( |
e120123e | 384 | const char *root, const git_tree_entry *entry, void *payload); |
da37654d VM |
385 | |
386 | /** Tree traversal modes */ | |
e120123e | 387 | typedef enum { |
da37654d VM |
388 | GIT_TREEWALK_PRE = 0, /* Pre-order */ |
389 | GIT_TREEWALK_POST = 1, /* Post-order */ | |
e120123e | 390 | } git_treewalk_mode; |
da37654d VM |
391 | |
392 | /** | |
16248ee2 | 393 | * Traverse the entries in a tree and its subtrees in post or pre order. |
da37654d | 394 | * |
16248ee2 RB |
395 | * The entries will be traversed in the specified order, children subtrees |
396 | * will be automatically loaded as required, and the `callback` will be | |
397 | * called once per entry with the current (relative) root for the entry and | |
398 | * the entry data itself. | |
da37654d | 399 | * |
a6bf1687 | 400 | * If the callback returns a positive value, the passed entry will be |
16248ee2 | 401 | * skipped on the traversal (in pre mode). A negative value stops the walk. |
da37654d VM |
402 | * |
403 | * @param tree The tree to walk | |
da37654d | 404 | * @param mode Traversal mode (pre or post-order) |
e120123e | 405 | * @param callback Function to call on each tree entry |
2744806f | 406 | * @param payload Opaque pointer to be passed on each callback |
e172cf08 | 407 | * @return 0 or an error code |
da37654d | 408 | */ |
e120123e | 409 | GIT_EXTERN(int) git_tree_walk( |
f45d51ff | 410 | const git_tree *tree, |
e120123e RB |
411 | git_treewalk_mode mode, |
412 | git_treewalk_cb callback, | |
413 | void *payload); | |
da37654d | 414 | |
f0224772 ET |
415 | /** |
416 | * Create an in-memory copy of a tree. The copy must be explicitly | |
417 | * free'd or it will leak. | |
418 | * | |
419 | * @param out Pointer to store the copy of the tree | |
420 | * @param source Original tree to copy | |
421 | */ | |
422 | GIT_EXTERN(int) git_tree_dup(git_tree **out, git_tree *source); | |
423 | ||
9464f9eb CMN |
424 | /** |
425 | * The kind of update to perform | |
426 | */ | |
427 | typedef enum { | |
428 | /** Update or insert an entry at the specified path */ | |
429 | GIT_TREE_UPDATE_UPSERT, | |
430 | /** Remove an entry from the specified path */ | |
431 | GIT_TREE_UPDATE_REMOVE, | |
432 | } git_tree_update_t; | |
433 | ||
434 | /** | |
435 | * An action to perform during the update of a tree | |
436 | */ | |
437 | typedef struct { | |
438 | /** Update action. If it's an removal, only the path is looked at */ | |
439 | git_tree_update_t action; | |
440 | /** The entry's id */ | |
441 | git_oid id; | |
442 | /** The filemode/kind of object */ | |
443 | git_filemode_t filemode; | |
444 | /** The full path from the root tree */ | |
445 | const char *path; | |
446 | } git_tree_update; | |
447 | ||
448 | /** | |
449 | * Create a tree based on another one with the specified modifications | |
450 | * | |
451 | * Given the `baseline` perform the changes described in the list of | |
452 | * `updates` and create a new tree. | |
453 | * | |
454 | * This function is optimized for common file/directory addition, removal and | |
455 | * replacement in trees. It is much more efficient than reading the tree into a | |
456 | * `git_index` and modifying that, but in exchange it is not as flexible. | |
457 | * | |
458 | * Deleting and adding the same entry is undefined behaviour, changing | |
459 | * a tree to a blob or viceversa is not supported. | |
460 | * | |
461 | * @param out id of the new tree | |
462 | * @param repo the repository in which to create the tree, must be the | |
463 | * same as for `baseline` | |
464 | * @param baseline the tree to base these changes on | |
465 | * @param nupdates the number of elements in the update list | |
466 | * @param updates the list of updates to perform | |
c25aa7cd | 467 | * @return 0 or an error code |
9464f9eb CMN |
468 | */ |
469 | GIT_EXTERN(int) git_tree_create_updated(git_oid *out, git_repository *repo, git_tree *baseline, size_t nupdates, const git_tree_update *updates); | |
470 | ||
3a437590 RB |
471 | /** @} */ |
472 | ||
225fe215 VM |
473 | GIT_END_DECL |
474 | #endif |