]>
Commit | Line | Data |
---|---|---|
f5918330 | 1 | /* |
5e0de328 | 2 | * Copyright (C) 2009-2012 the libgit2 contributors |
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 | * |
1795f879 | 27 | * @param tree pointer to the looked up tree |
3315782c | 28 | * @param repo the repo to use when locating the tree. |
225fe215 | 29 | * @param id identity of the tree to locate. |
e172cf08 | 30 | * @return 0 or an error code |
225fe215 | 31 | */ |
e52ed7a5 VM |
32 | GIT_INLINE(int) git_tree_lookup(git_tree **tree, git_repository *repo, const git_oid *id) |
33 | { | |
5de079b8 | 34 | return git_object_lookup((git_object **)tree, repo, id, GIT_OBJ_TREE); |
e52ed7a5 | 35 | } |
d8603ed9 | 36 | |
790c6c95 MP |
37 | /** |
38 | * Lookup a tree object from the repository, | |
39 | * given a prefix of its identifier (short id). | |
40 | * | |
41 | * @see git_object_lookup_prefix | |
42 | * | |
43 | * @param tree pointer to the looked up tree | |
44 | * @param repo the repo to use when locating the tree. | |
45 | * @param id identity of the tree to locate. | |
46 | * @param len the length of the short identifier | |
e172cf08 | 47 | * @return 0 or an error code |
790c6c95 | 48 | */ |
0e2fcca8 VM |
49 | GIT_INLINE(int) git_tree_lookup_prefix( |
50 | git_tree **tree, | |
51 | git_repository *repo, | |
52 | const git_oid *id, | |
b8457baa | 53 | size_t len) |
790c6c95 MP |
54 | { |
55 | return git_object_lookup_prefix((git_object **)tree, repo, id, len, GIT_OBJ_TREE); | |
56 | } | |
57 | ||
b0b83135 CMN |
58 | /** |
59 | * Close an open tree | |
60 | * | |
45e79e37 | 61 | * This is a wrapper around git_object_free() |
b0b83135 CMN |
62 | * |
63 | * IMPORTANT: | |
64 | * It *is* necessary to call this method when you stop | |
65 | * using a tree. Failure to do so will cause a memory leak. | |
66 | * | |
67 | * @param tree the tree to close | |
68 | */ | |
45e79e37 | 69 | GIT_INLINE(void) git_tree_free(git_tree *tree) |
b0b83135 | 70 | { |
45e79e37 | 71 | git_object_free((git_object *) tree); |
b0b83135 CMN |
72 | } |
73 | ||
0e2fcca8 VM |
74 | /** |
75 | * Free a tree entry | |
76 | * | |
77 | * IMPORTANT: This function is only needed for tree | |
78 | * entries owned by the user, such as the ones returned | |
46ea40d9 | 79 | * by `git_tree_entry_dup`. |
0e2fcca8 VM |
80 | * |
81 | * @param entry The entry to free | |
82 | */ | |
83 | GIT_EXTERN(void) git_tree_entry_free(git_tree_entry *entry); | |
84 | ||
85 | /** | |
86 | * Duplicate a tree entry | |
87 | * | |
88 | * Create a copy of a tree entry. The returned copy is owned | |
89 | * by the user, and must be freed manually with | |
90 | * `git_tree_entry_free`. | |
91 | * | |
92 | * @param entry A tree entry to duplicate | |
93 | * @return a copy of the original entry | |
94 | */ | |
46ea40d9 | 95 | GIT_EXTERN(git_tree_entry *) git_tree_entry_dup(const git_tree_entry *entry); |
b0b83135 | 96 | |
225fe215 VM |
97 | /** |
98 | * Get the id of a tree. | |
72a3fe42 | 99 | * |
225fe215 VM |
100 | * @param tree a previously loaded tree. |
101 | * @return object identity for the tree. | |
102 | */ | |
103 | GIT_EXTERN(const git_oid *) git_tree_id(git_tree *tree); | |
104 | ||
003c2690 VM |
105 | /** |
106 | * Get the number of entries listed in a tree | |
72a3fe42 | 107 | * |
003c2690 VM |
108 | * @param tree a previously loaded tree. |
109 | * @return the number of entries in the tree | |
110 | */ | |
e5c80097 | 111 | GIT_EXTERN(unsigned int) git_tree_entrycount(git_tree *tree); |
003c2690 VM |
112 | |
113 | /** | |
114 | * Lookup a tree entry by its filename | |
72a3fe42 | 115 | * |
003c2690 VM |
116 | * @param tree a previously loaded tree. |
117 | * @param filename the filename of the desired entry | |
118 | * @return the tree entry; NULL if not found | |
119 | */ | |
0ad6efa1 | 120 | GIT_EXTERN(const git_tree_entry *) git_tree_entry_byname(git_tree *tree, const char *filename); |
003c2690 VM |
121 | |
122 | /** | |
123 | * Lookup a tree entry by its position in the tree | |
72a3fe42 | 124 | * |
003c2690 VM |
125 | * @param tree a previously loaded tree. |
126 | * @param idx the position in the entry list | |
127 | * @return the tree entry; NULL if not found | |
128 | */ | |
b8457baa | 129 | GIT_EXTERN(const git_tree_entry *) git_tree_entry_byindex(git_tree *tree, size_t idx); |
003c2690 | 130 | |
2031760c RB |
131 | /** |
132 | * Lookup a tree entry by SHA value. | |
133 | * | |
134 | * Warning: this must examine every entry in the tree, so it is not fast. | |
135 | * | |
136 | * @param tree a previously loaded tree. | |
137 | * @param oid the sha being looked for | |
138 | * @return the tree entry; NULL if not found | |
139 | */ | |
140 | GIT_EXTERN(const git_tree_entry *) git_tree_entry_byoid(git_tree *tree, const git_oid *oid); | |
141 | ||
003c2690 VM |
142 | /** |
143 | * Get the UNIX file attributes of a tree entry | |
72a3fe42 | 144 | * |
003c2690 | 145 | * @param entry a tree entry |
9d7ac675 | 146 | * @return filemode as an integer |
003c2690 | 147 | */ |
9d7ac675 | 148 | GIT_EXTERN(git_filemode_t) git_tree_entry_filemode(const git_tree_entry *entry); |
003c2690 VM |
149 | |
150 | /** | |
151 | * Get the filename of a tree entry | |
72a3fe42 | 152 | * |
003c2690 VM |
153 | * @param entry a tree entry |
154 | * @return the name of the file | |
155 | */ | |
0ad6efa1 | 156 | GIT_EXTERN(const char *) git_tree_entry_name(const git_tree_entry *entry); |
003c2690 VM |
157 | |
158 | /** | |
159 | * Get the id of the object pointed by the entry | |
72a3fe42 | 160 | * |
003c2690 VM |
161 | * @param entry a tree entry |
162 | * @return the oid of the object | |
163 | */ | |
0ad6efa1 | 164 | GIT_EXTERN(const git_oid *) git_tree_entry_id(const git_tree_entry *entry); |
003c2690 | 165 | |
ff9a4c13 RG |
166 | /** |
167 | * Get the type of the object pointed by the entry | |
168 | * | |
169 | * @param entry a tree entry | |
170 | * @return the type of the pointed object | |
171 | */ | |
172 | GIT_EXTERN(git_otype) git_tree_entry_type(const git_tree_entry *entry); | |
173 | ||
003c2690 | 174 | /** |
f49a2e49 | 175 | * Convert a tree entry to the git_object it points too. |
1795f879 VM |
176 | * |
177 | * @param object pointer to the converted object | |
72a3fe42 | 178 | * @param repo repository where to lookup the pointed object |
003c2690 | 179 | * @param entry a tree entry |
e172cf08 | 180 | * @return 0 or an error code |
003c2690 | 181 | */ |
0e2fcca8 VM |
182 | GIT_EXTERN(int) git_tree_entry_to_object( |
183 | git_object **object_out, | |
184 | git_repository *repo, | |
185 | const git_tree_entry *entry); | |
003c2690 | 186 | |
47d8ec56 | 187 | /** |
29e1789b VM |
188 | * Write a tree to the ODB from the index file |
189 | * | |
190 | * This method will scan the index and write a representation | |
191 | * of its current state back to disk; it recursively creates | |
192 | * tree objects for each of the subtrees stored in the index, | |
193 | * but only returns the OID of the root tree. This is the OID | |
194 | * that can be used e.g. to create a commit. | |
195 | * | |
196 | * The index instance cannot be bare, and needs to be associated | |
197 | * to an existing repository. | |
198 | * | |
199 | * @param oid Pointer where to store the written tree | |
200 | * @param index Index to write | |
e172cf08 | 201 | * @return 0 or an error code |
47d8ec56 | 202 | */ |
29e1789b | 203 | GIT_EXTERN(int) git_tree_create_fromindex(git_oid *oid, git_index *index); |
47d8ec56 | 204 | |
0ad6efa1 VM |
205 | /** |
206 | * Create a new tree builder. | |
207 | * | |
208 | * The tree builder can be used to create or modify | |
209 | * trees in memory and write them as tree objects to the | |
210 | * database. | |
211 | * | |
212 | * If the `source` parameter is not NULL, the tree builder | |
213 | * will be initialized with the entries of the given tree. | |
932d1baf | 214 | * |
0ad6efa1 VM |
215 | * If the `source` parameter is NULL, the tree builder will |
216 | * have no entries and will have to be filled manually. | |
217 | * | |
218 | * @param builder_p Pointer where to store the tree builder | |
219 | * @param source Source tree to initialize the builder (optional) | |
d73c94b2 | 220 | * @return 0 on success; error code otherwise |
0ad6efa1 VM |
221 | */ |
222 | GIT_EXTERN(int) git_treebuilder_create(git_treebuilder **builder_p, const git_tree *source); | |
223 | ||
224 | /** | |
225 | * Clear all the entires in the builder | |
226 | * | |
227 | * @param bld Builder to clear | |
228 | */ | |
229 | GIT_EXTERN(void) git_treebuilder_clear(git_treebuilder *bld); | |
230 | ||
231 | /** | |
232 | * Free a tree builder | |
233 | * | |
234 | * This will clear all the entries and free to builder. | |
235 | * Failing to free the builder after you're done using it | |
236 | * will result in a memory leak | |
237 | * | |
238 | * @param bld Builder to free | |
239 | */ | |
240 | GIT_EXTERN(void) git_treebuilder_free(git_treebuilder *bld); | |
241 | ||
242 | /** | |
243 | * Get an entry from the builder from its filename | |
244 | * | |
245 | * The returned entry is owned by the builder and should | |
246 | * not be freed manually. | |
247 | * | |
248 | * @param bld Tree builder | |
249 | * @param filename Name of the entry | |
250 | * @return pointer to the entry; NULL if not found | |
251 | */ | |
252 | GIT_EXTERN(const git_tree_entry *) git_treebuilder_get(git_treebuilder *bld, const char *filename); | |
253 | ||
254 | /** | |
255 | * Add or update an entry to the builder | |
256 | * | |
257 | * Insert a new entry for `filename` in the builder with the | |
258 | * given attributes. | |
259 | * | |
260 | * if an entry named `filename` already exists, its attributes | |
261 | * will be updated with the given ones. | |
262 | * | |
263 | * The optional pointer `entry_out` can be used to retrieve a | |
264 | * pointer to the newly created/updated entry. | |
265 | * | |
66439b0b | 266 | * No attempt is being made to ensure that the provided oid points |
267 | * to an existing git object in the object database, nor that the | |
268 | * attributes make sense regarding the type of the pointed at object. | |
269 | * | |
0ad6efa1 VM |
270 | * @param entry_out Pointer to store the entry (optional) |
271 | * @param bld Tree builder | |
272 | * @param filename Filename of the entry | |
273 | * @param id SHA1 oid of the entry | |
a7dbac0b | 274 | * @param filemode Folder attributes of the entry. This parameter must |
66439b0b | 275 | * be valued with one of the following entries: 0040000, 0100644, |
276 | * 0100755, 0120000 or 0160000. | |
e172cf08 | 277 | * @return 0 or an error code |
0ad6efa1 | 278 | */ |
0e2fcca8 VM |
279 | GIT_EXTERN(int) git_treebuilder_insert( |
280 | const git_tree_entry **entry_out, | |
281 | git_treebuilder *bld, | |
282 | const char *filename, | |
283 | const git_oid *id, | |
a7dbac0b | 284 | git_filemode_t filemode); |
0ad6efa1 VM |
285 | |
286 | /** | |
287 | * Remove an entry from the builder by its filename | |
288 | * | |
289 | * @param bld Tree builder | |
290 | * @param filename Filename of the entry to remove | |
291 | */ | |
292 | GIT_EXTERN(int) git_treebuilder_remove(git_treebuilder *bld, const char *filename); | |
293 | ||
294 | /** | |
295 | * Filter the entries in the tree | |
296 | * | |
297 | * The `filter` callback will be called for each entry | |
298 | * in the tree with a pointer to the entry and the | |
299 | * provided `payload`: if the callback returns 1, the | |
300 | * entry will be filtered (removed from the builder). | |
301 | * | |
302 | * @param bld Tree builder | |
303 | * @param filter Callback to filter entries | |
304 | */ | |
0e2fcca8 VM |
305 | GIT_EXTERN(void) git_treebuilder_filter( |
306 | git_treebuilder *bld, | |
307 | int (*filter)(const git_tree_entry *, void *), | |
308 | void *payload); | |
0ad6efa1 VM |
309 | |
310 | /** | |
311 | * Write the contents of the tree builder as a tree object | |
312 | * | |
313 | * The tree builder will be written to the given `repo`, and | |
314 | * it's identifying SHA1 hash will be stored in the `oid` | |
315 | * pointer. | |
316 | * | |
317 | * @param oid Pointer where to store the written OID | |
318 | * @param repo Repository where to store the object | |
319 | * @param bld Tree builder to write | |
e172cf08 | 320 | * @return 0 or an error code |
0ad6efa1 VM |
321 | */ |
322 | GIT_EXTERN(int) git_treebuilder_write(git_oid *oid, git_repository *repo, git_treebuilder *bld); | |
323 | ||
3fa735ca | 324 | /** |
0e2fcca8 VM |
325 | * Retrieve a tree entry contained in a tree or in any |
326 | * of its subtrees, given its relative path. | |
3fa735ca | 327 | * |
0e2fcca8 VM |
328 | * The returned tree entry is owned by the user and must |
329 | * be freed manually with `git_tree_entry_free`. | |
3fa735ca | 330 | * |
0e2fcca8 | 331 | * @param entry Pointer where to store the tree entry |
3fa735ca | 332 | * @param root A previously loaded tree which will be the root of the relative path |
0e2fcca8 VM |
333 | * @param subtree_path Path to the contained entry |
334 | * @return 0 on success; GIT_ENOTFOUND if the path does not exist | |
3fa735ca | 335 | */ |
0e2fcca8 VM |
336 | GIT_EXTERN(int) git_tree_entry_bypath( |
337 | git_tree_entry **entry, | |
338 | git_tree *root, | |
339 | const char *path); | |
da37654d VM |
340 | |
341 | /** Callback for the tree traversal method */ | |
0e2fcca8 | 342 | typedef int (*git_treewalk_cb)(const char *root, const git_tree_entry *entry, void *payload); |
da37654d VM |
343 | |
344 | /** Tree traversal modes */ | |
345 | enum git_treewalk_mode { | |
346 | GIT_TREEWALK_PRE = 0, /* Pre-order */ | |
347 | GIT_TREEWALK_POST = 1, /* Post-order */ | |
348 | }; | |
349 | ||
350 | /** | |
351 | * Traverse the entries in a tree and its subtrees in | |
352 | * post or pre order | |
353 | * | |
354 | * The entries will be traversed in the specified order, | |
355 | * children subtrees will be automatically loaded as required, | |
356 | * and the `callback` will be called once per entry with | |
357 | * the current (relative) root for the entry and the entry | |
358 | * data itself. | |
359 | * | |
a6bf1687 CMN |
360 | * If the callback returns a positive value, the passed entry will be |
361 | * skipped on the traversal (in pre mode). A negative value stops the | |
362 | * walk. | |
da37654d VM |
363 | * |
364 | * @param tree The tree to walk | |
365 | * @param callback Function to call on each tree entry | |
366 | * @param mode Traversal mode (pre or post-order) | |
2744806f | 367 | * @param payload Opaque pointer to be passed on each callback |
e172cf08 | 368 | * @return 0 or an error code |
da37654d | 369 | */ |
2744806f | 370 | GIT_EXTERN(int) git_tree_walk(git_tree *tree, git_treewalk_cb callback, int mode, void *payload); |
da37654d | 371 | |
3a437590 RB |
372 | /** @} */ |
373 | ||
225fe215 VM |
374 | GIT_END_DECL |
375 | #endif |