]>
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 | * | |
41 | * @param tree pointer to the looked up tree | |
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 RB |
99 | GIT_EXTERN(const git_tree_entry *) git_tree_entry_byname( |
100 | 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 RB |
112 | GIT_EXTERN(const git_tree_entry *) git_tree_entry_byindex( |
113 | 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. | |
124 | * @param oid the sha being looked for | |
125 | * @return the tree entry; NULL if not found | |
126 | */ | |
e120123e | 127 | GIT_EXTERN(const git_tree_entry *) git_tree_entry_byoid( |
16248ee2 | 128 | const git_tree *tree, const git_oid *oid); |
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 | |
139 | * @param subtree_path Path to the contained entry | |
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, | |
144 | git_tree *root, | |
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 | * | |
153 | * @param entry A tree entry to duplicate | |
154 | * @return a copy of the original entry or NULL on error (alloc failure) | |
155 | */ | |
156 | GIT_EXTERN(git_tree_entry *) git_tree_entry_dup(const git_tree_entry *entry); | |
157 | ||
158 | /** | |
159 | * Free a user-owned tree entry | |
160 | * | |
161 | * IMPORTANT: This function is only needed for tree entries owned by the | |
162 | * user, such as the ones returned by `git_tree_entry_dup()` or | |
163 | * `git_tree_entry_bypath()`. | |
164 | * | |
165 | * @param entry The entry to free | |
166 | */ | |
167 | GIT_EXTERN(void) git_tree_entry_free(git_tree_entry *entry); | |
003c2690 VM |
168 | |
169 | /** | |
170 | * Get the filename of a tree entry | |
72a3fe42 | 171 | * |
003c2690 VM |
172 | * @param entry a tree entry |
173 | * @return the name of the file | |
174 | */ | |
0ad6efa1 | 175 | GIT_EXTERN(const char *) git_tree_entry_name(const git_tree_entry *entry); |
003c2690 VM |
176 | |
177 | /** | |
178 | * Get the id of the object pointed by the entry | |
72a3fe42 | 179 | * |
003c2690 VM |
180 | * @param entry a tree entry |
181 | * @return the oid of the object | |
182 | */ | |
0ad6efa1 | 183 | GIT_EXTERN(const git_oid *) git_tree_entry_id(const git_tree_entry *entry); |
003c2690 | 184 | |
ff9a4c13 RG |
185 | /** |
186 | * Get the type of the object pointed by the entry | |
187 | * | |
188 | * @param entry a tree entry | |
189 | * @return the type of the pointed object | |
190 | */ | |
191 | GIT_EXTERN(git_otype) git_tree_entry_type(const git_tree_entry *entry); | |
192 | ||
e120123e RB |
193 | /** |
194 | * Get the UNIX file attributes of a tree entry | |
195 | * | |
196 | * @param entry a tree entry | |
197 | * @return filemode as an integer | |
198 | */ | |
199 | GIT_EXTERN(git_filemode_t) git_tree_entry_filemode(const git_tree_entry *entry); | |
200 | ||
98527b5b RB |
201 | /** |
202 | * Compare two tree entries | |
203 | * | |
204 | * @param e1 first tree entry | |
205 | * @param e2 second tree entry | |
206 | * @return <0 if e1 is before e2, 0 if e1 == e2, >0 if e1 is after e2 | |
207 | */ | |
208 | GIT_EXTERN(int) git_tree_entry_cmp(const git_tree_entry *e1, const git_tree_entry *e2); | |
209 | ||
003c2690 | 210 | /** |
f49a2e49 | 211 | * Convert a tree entry to the git_object it points too. |
1795f879 | 212 | * |
e120123e RB |
213 | * You must call `git_object_free()` on the object when you are done with it. |
214 | * | |
1795f879 | 215 | * @param object pointer to the converted object |
72a3fe42 | 216 | * @param repo repository where to lookup the pointed object |
003c2690 | 217 | * @param entry a tree entry |
e172cf08 | 218 | * @return 0 or an error code |
003c2690 | 219 | */ |
0e2fcca8 VM |
220 | GIT_EXTERN(int) git_tree_entry_to_object( |
221 | git_object **object_out, | |
222 | git_repository *repo, | |
223 | const git_tree_entry *entry); | |
003c2690 | 224 | |
0ad6efa1 VM |
225 | /** |
226 | * Create a new tree builder. | |
227 | * | |
e120123e RB |
228 | * The tree builder can be used to create or modify trees in memory and |
229 | * write them as tree objects to the database. | |
0ad6efa1 | 230 | * |
e120123e RB |
231 | * If the `source` parameter is not NULL, the tree builder will be |
232 | * initialized with the entries of the given tree. | |
932d1baf | 233 | * |
e120123e RB |
234 | * If the `source` parameter is NULL, the tree builder will start with no |
235 | * entries and will have to be filled manually. | |
0ad6efa1 | 236 | * |
e120123e | 237 | * @param out Pointer where to store the tree builder |
0ad6efa1 | 238 | * @param source Source tree to initialize the builder (optional) |
d73c94b2 | 239 | * @return 0 on success; error code otherwise |
0ad6efa1 | 240 | */ |
e120123e RB |
241 | GIT_EXTERN(int) git_treebuilder_create( |
242 | git_treebuilder **out, const git_tree *source); | |
0ad6efa1 VM |
243 | |
244 | /** | |
245 | * Clear all the entires in the builder | |
246 | * | |
247 | * @param bld Builder to clear | |
248 | */ | |
249 | GIT_EXTERN(void) git_treebuilder_clear(git_treebuilder *bld); | |
250 | ||
5fb98206 JW |
251 | /** |
252 | * Get the number of entries listed in a treebuilder | |
253 | * | |
254 | * @param tree a previously loaded treebuilder. | |
255 | * @return the number of entries in the treebuilder | |
256 | */ | |
257 | GIT_EXTERN(unsigned int) git_treebuilder_entrycount(git_treebuilder *bld); | |
258 | ||
0ad6efa1 VM |
259 | /** |
260 | * Free a tree builder | |
261 | * | |
262 | * This will clear all the entries and free to builder. | |
263 | * Failing to free the builder after you're done using it | |
264 | * will result in a memory leak | |
265 | * | |
266 | * @param bld Builder to free | |
267 | */ | |
268 | GIT_EXTERN(void) git_treebuilder_free(git_treebuilder *bld); | |
269 | ||
270 | /** | |
271 | * Get an entry from the builder from its filename | |
272 | * | |
273 | * The returned entry is owned by the builder and should | |
274 | * not be freed manually. | |
275 | * | |
276 | * @param bld Tree builder | |
277 | * @param filename Name of the entry | |
278 | * @return pointer to the entry; NULL if not found | |
279 | */ | |
e120123e RB |
280 | GIT_EXTERN(const git_tree_entry *) git_treebuilder_get( |
281 | git_treebuilder *bld, const char *filename); | |
0ad6efa1 VM |
282 | |
283 | /** | |
284 | * Add or update an entry to the builder | |
285 | * | |
286 | * Insert a new entry for `filename` in the builder with the | |
287 | * given attributes. | |
288 | * | |
e120123e | 289 | * If an entry named `filename` already exists, its attributes |
0ad6efa1 VM |
290 | * will be updated with the given ones. |
291 | * | |
e120123e RB |
292 | * The optional pointer `out` can be used to retrieve a pointer to |
293 | * the newly created/updated entry. Pass NULL if you do not need it. | |
0ad6efa1 | 294 | * |
66439b0b | 295 | * No attempt is being made to ensure that the provided oid points |
296 | * to an existing git object in the object database, nor that the | |
297 | * attributes make sense regarding the type of the pointed at object. | |
298 | * | |
e120123e | 299 | * @param out Pointer to store the entry (optional) |
0ad6efa1 VM |
300 | * @param bld Tree builder |
301 | * @param filename Filename of the entry | |
302 | * @param id SHA1 oid of the entry | |
a7dbac0b | 303 | * @param filemode Folder attributes of the entry. This parameter must |
66439b0b | 304 | * be valued with one of the following entries: 0040000, 0100644, |
305 | * 0100755, 0120000 or 0160000. | |
e172cf08 | 306 | * @return 0 or an error code |
0ad6efa1 | 307 | */ |
0e2fcca8 | 308 | GIT_EXTERN(int) git_treebuilder_insert( |
e120123e | 309 | const git_tree_entry **out, |
0e2fcca8 VM |
310 | git_treebuilder *bld, |
311 | const char *filename, | |
312 | const git_oid *id, | |
a7dbac0b | 313 | git_filemode_t filemode); |
0ad6efa1 VM |
314 | |
315 | /** | |
316 | * Remove an entry from the builder by its filename | |
317 | * | |
318 | * @param bld Tree builder | |
319 | * @param filename Filename of the entry to remove | |
320 | */ | |
e120123e RB |
321 | GIT_EXTERN(int) git_treebuilder_remove( |
322 | git_treebuilder *bld, const char *filename); | |
323 | ||
324 | typedef int (*git_treebuilder_filter_cb)( | |
325 | const git_tree_entry *entry, void *payload); | |
0ad6efa1 VM |
326 | |
327 | /** | |
328 | * Filter the entries in the tree | |
329 | * | |
e120123e RB |
330 | * The `filter` callback will be called for each entry in the tree with a |
331 | * pointer to the entry and the provided `payload`; if the callback returns | |
332 | * non-zero, the entry will be filtered (removed from the builder). | |
0ad6efa1 VM |
333 | * |
334 | * @param bld Tree builder | |
335 | * @param filter Callback to filter entries | |
e120123e | 336 | * @param payload Extra data to pass to filter |
0ad6efa1 | 337 | */ |
0e2fcca8 VM |
338 | GIT_EXTERN(void) git_treebuilder_filter( |
339 | git_treebuilder *bld, | |
e120123e | 340 | git_treebuilder_filter_cb filter, |
0e2fcca8 | 341 | void *payload); |
0ad6efa1 VM |
342 | |
343 | /** | |
344 | * Write the contents of the tree builder as a tree object | |
345 | * | |
e120123e RB |
346 | * The tree builder will be written to the given `repo`, and its |
347 | * identifying SHA1 hash will be stored in the `id` pointer. | |
0ad6efa1 | 348 | * |
e120123e RB |
349 | * @param id Pointer to store the OID of the newly written tree |
350 | * @param repo Repository in which to store the object | |
0ad6efa1 | 351 | * @param bld Tree builder to write |
e172cf08 | 352 | * @return 0 or an error code |
0ad6efa1 | 353 | */ |
e120123e RB |
354 | GIT_EXTERN(int) git_treebuilder_write( |
355 | git_oid *id, git_repository *repo, git_treebuilder *bld); | |
0ad6efa1 | 356 | |
da37654d VM |
357 | |
358 | /** Callback for the tree traversal method */ | |
e120123e RB |
359 | typedef int (*git_treewalk_cb)( |
360 | const char *root, const git_tree_entry *entry, void *payload); | |
da37654d VM |
361 | |
362 | /** Tree traversal modes */ | |
e120123e | 363 | typedef enum { |
da37654d VM |
364 | GIT_TREEWALK_PRE = 0, /* Pre-order */ |
365 | GIT_TREEWALK_POST = 1, /* Post-order */ | |
e120123e | 366 | } git_treewalk_mode; |
da37654d VM |
367 | |
368 | /** | |
16248ee2 | 369 | * Traverse the entries in a tree and its subtrees in post or pre order. |
da37654d | 370 | * |
16248ee2 RB |
371 | * The entries will be traversed in the specified order, children subtrees |
372 | * will be automatically loaded as required, and the `callback` will be | |
373 | * called once per entry with the current (relative) root for the entry and | |
374 | * the entry data itself. | |
da37654d | 375 | * |
a6bf1687 | 376 | * If the callback returns a positive value, the passed entry will be |
16248ee2 | 377 | * skipped on the traversal (in pre mode). A negative value stops the walk. |
da37654d VM |
378 | * |
379 | * @param tree The tree to walk | |
da37654d | 380 | * @param mode Traversal mode (pre or post-order) |
e120123e | 381 | * @param callback Function to call on each tree entry |
2744806f | 382 | * @param payload Opaque pointer to be passed on each callback |
e172cf08 | 383 | * @return 0 or an error code |
da37654d | 384 | */ |
e120123e | 385 | GIT_EXTERN(int) git_tree_walk( |
f45d51ff | 386 | const git_tree *tree, |
e120123e RB |
387 | git_treewalk_mode mode, |
388 | git_treewalk_cb callback, | |
389 | void *payload); | |
da37654d | 390 | |
3a437590 RB |
391 | /** @} */ |
392 | ||
225fe215 VM |
393 | GIT_END_DECL |
394 | #endif |