]>
Commit | Line | Data |
---|---|---|
f5918330 | 1 | /* |
bb742ede | 2 | * Copyright (C) 2009-2011 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. |
d9111722 | 30 | * @return GIT_SUCCESS 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 | |
d9111722 | 47 | * @return GIT_SUCCESS or an error code |
790c6c95 MP |
48 | */ |
49 | GIT_INLINE(int) git_tree_lookup_prefix(git_tree **tree, git_repository *repo, const git_oid *id, unsigned int len) | |
50 | { | |
51 | return git_object_lookup_prefix((git_object **)tree, repo, id, len, GIT_OBJ_TREE); | |
52 | } | |
53 | ||
b0b83135 CMN |
54 | /** |
55 | * Close an open tree | |
56 | * | |
57 | * This is a wrapper around git_object_close() | |
58 | * | |
59 | * IMPORTANT: | |
60 | * It *is* necessary to call this method when you stop | |
61 | * using a tree. Failure to do so will cause a memory leak. | |
62 | * | |
63 | * @param tree the tree to close | |
64 | */ | |
65 | ||
66 | GIT_INLINE(void) git_tree_close(git_tree *tree) | |
67 | { | |
c0ffe518 | 68 | git_object_close((git_object *) tree); |
b0b83135 CMN |
69 | } |
70 | ||
71 | ||
225fe215 VM |
72 | /** |
73 | * Get the id of a tree. | |
72a3fe42 | 74 | * |
225fe215 VM |
75 | * @param tree a previously loaded tree. |
76 | * @return object identity for the tree. | |
77 | */ | |
78 | GIT_EXTERN(const git_oid *) git_tree_id(git_tree *tree); | |
79 | ||
003c2690 VM |
80 | /** |
81 | * Get the number of entries listed in a tree | |
72a3fe42 | 82 | * |
003c2690 VM |
83 | * @param tree a previously loaded tree. |
84 | * @return the number of entries in the tree | |
85 | */ | |
e5c80097 | 86 | GIT_EXTERN(unsigned int) git_tree_entrycount(git_tree *tree); |
003c2690 VM |
87 | |
88 | /** | |
89 | * Lookup a tree entry by its filename | |
72a3fe42 | 90 | * |
003c2690 VM |
91 | * @param tree a previously loaded tree. |
92 | * @param filename the filename of the desired entry | |
93 | * @return the tree entry; NULL if not found | |
94 | */ | |
0ad6efa1 | 95 | GIT_EXTERN(const git_tree_entry *) git_tree_entry_byname(git_tree *tree, const char *filename); |
003c2690 VM |
96 | |
97 | /** | |
98 | * Lookup a tree entry by its position in the tree | |
72a3fe42 | 99 | * |
003c2690 VM |
100 | * @param tree a previously loaded tree. |
101 | * @param idx the position in the entry list | |
102 | * @return the tree entry; NULL if not found | |
103 | */ | |
e5c80097 | 104 | GIT_EXTERN(const git_tree_entry *) git_tree_entry_byindex(git_tree *tree, unsigned int idx); |
003c2690 VM |
105 | |
106 | /** | |
107 | * Get the UNIX file attributes of a tree entry | |
72a3fe42 | 108 | * |
003c2690 VM |
109 | * @param entry a tree entry |
110 | * @return attributes as an integer | |
111 | */ | |
0ad6efa1 | 112 | GIT_EXTERN(unsigned int) git_tree_entry_attributes(const git_tree_entry *entry); |
003c2690 VM |
113 | |
114 | /** | |
115 | * Get the filename of a tree entry | |
72a3fe42 | 116 | * |
003c2690 VM |
117 | * @param entry a tree entry |
118 | * @return the name of the file | |
119 | */ | |
0ad6efa1 | 120 | GIT_EXTERN(const char *) git_tree_entry_name(const git_tree_entry *entry); |
003c2690 VM |
121 | |
122 | /** | |
123 | * Get the id of the object pointed by the entry | |
72a3fe42 | 124 | * |
003c2690 VM |
125 | * @param entry a tree entry |
126 | * @return the oid of the object | |
127 | */ | |
0ad6efa1 | 128 | GIT_EXTERN(const git_oid *) git_tree_entry_id(const git_tree_entry *entry); |
003c2690 | 129 | |
ff9a4c13 RG |
130 | /** |
131 | * Get the type of the object pointed by the entry | |
132 | * | |
133 | * @param entry a tree entry | |
134 | * @return the type of the pointed object | |
135 | */ | |
136 | GIT_EXTERN(git_otype) git_tree_entry_type(const git_tree_entry *entry); | |
137 | ||
003c2690 | 138 | /** |
f49a2e49 | 139 | * Convert a tree entry to the git_object it points too. |
1795f879 VM |
140 | * |
141 | * @param object pointer to the converted object | |
72a3fe42 | 142 | * @param repo repository where to lookup the pointed object |
003c2690 | 143 | * @param entry a tree entry |
d9111722 | 144 | * @return GIT_SUCCESS or an error code |
003c2690 | 145 | */ |
0ad6efa1 | 146 | GIT_EXTERN(int) git_tree_entry_2object(git_object **object_out, git_repository *repo, const git_tree_entry *entry); |
003c2690 | 147 | |
47d8ec56 | 148 | /** |
29e1789b VM |
149 | * Write a tree to the ODB from the index file |
150 | * | |
151 | * This method will scan the index and write a representation | |
152 | * of its current state back to disk; it recursively creates | |
153 | * tree objects for each of the subtrees stored in the index, | |
154 | * but only returns the OID of the root tree. This is the OID | |
155 | * that can be used e.g. to create a commit. | |
156 | * | |
157 | * The index instance cannot be bare, and needs to be associated | |
158 | * to an existing repository. | |
159 | * | |
160 | * @param oid Pointer where to store the written tree | |
161 | * @param index Index to write | |
d9111722 | 162 | * @return GIT_SUCCESS or an error code |
47d8ec56 | 163 | */ |
29e1789b | 164 | GIT_EXTERN(int) git_tree_create_fromindex(git_oid *oid, git_index *index); |
47d8ec56 | 165 | |
0ad6efa1 VM |
166 | /** |
167 | * Create a new tree builder. | |
168 | * | |
169 | * The tree builder can be used to create or modify | |
170 | * trees in memory and write them as tree objects to the | |
171 | * database. | |
172 | * | |
173 | * If the `source` parameter is not NULL, the tree builder | |
174 | * will be initialized with the entries of the given tree. | |
932d1baf | 175 | * |
0ad6efa1 VM |
176 | * If the `source` parameter is NULL, the tree builder will |
177 | * have no entries and will have to be filled manually. | |
178 | * | |
179 | * @param builder_p Pointer where to store the tree builder | |
180 | * @param source Source tree to initialize the builder (optional) | |
181 | * @return 0 on sucess; error code otherwise | |
182 | */ | |
183 | GIT_EXTERN(int) git_treebuilder_create(git_treebuilder **builder_p, const git_tree *source); | |
184 | ||
185 | /** | |
186 | * Clear all the entires in the builder | |
187 | * | |
188 | * @param bld Builder to clear | |
189 | */ | |
190 | GIT_EXTERN(void) git_treebuilder_clear(git_treebuilder *bld); | |
191 | ||
192 | /** | |
193 | * Free a tree builder | |
194 | * | |
195 | * This will clear all the entries and free to builder. | |
196 | * Failing to free the builder after you're done using it | |
197 | * will result in a memory leak | |
198 | * | |
199 | * @param bld Builder to free | |
200 | */ | |
201 | GIT_EXTERN(void) git_treebuilder_free(git_treebuilder *bld); | |
202 | ||
203 | /** | |
204 | * Get an entry from the builder from its filename | |
205 | * | |
206 | * The returned entry is owned by the builder and should | |
207 | * not be freed manually. | |
208 | * | |
209 | * @param bld Tree builder | |
210 | * @param filename Name of the entry | |
211 | * @return pointer to the entry; NULL if not found | |
212 | */ | |
213 | GIT_EXTERN(const git_tree_entry *) git_treebuilder_get(git_treebuilder *bld, const char *filename); | |
214 | ||
215 | /** | |
216 | * Add or update an entry to the builder | |
217 | * | |
218 | * Insert a new entry for `filename` in the builder with the | |
219 | * given attributes. | |
220 | * | |
221 | * if an entry named `filename` already exists, its attributes | |
222 | * will be updated with the given ones. | |
223 | * | |
224 | * The optional pointer `entry_out` can be used to retrieve a | |
225 | * pointer to the newly created/updated entry. | |
226 | * | |
227 | * @param entry_out Pointer to store the entry (optional) | |
228 | * @param bld Tree builder | |
229 | * @param filename Filename of the entry | |
230 | * @param id SHA1 oid of the entry | |
231 | * @param attributes Folder attributes of the entry | |
d9111722 | 232 | * @return GIT_SUCCESS or an error code |
0ad6efa1 VM |
233 | */ |
234 | GIT_EXTERN(int) git_treebuilder_insert(git_tree_entry **entry_out, git_treebuilder *bld, const char *filename, const git_oid *id, unsigned int attributes); | |
235 | ||
236 | /** | |
237 | * Remove an entry from the builder by its filename | |
238 | * | |
239 | * @param bld Tree builder | |
240 | * @param filename Filename of the entry to remove | |
241 | */ | |
242 | GIT_EXTERN(int) git_treebuilder_remove(git_treebuilder *bld, const char *filename); | |
243 | ||
244 | /** | |
245 | * Filter the entries in the tree | |
246 | * | |
247 | * The `filter` callback will be called for each entry | |
248 | * in the tree with a pointer to the entry and the | |
249 | * provided `payload`: if the callback returns 1, the | |
250 | * entry will be filtered (removed from the builder). | |
251 | * | |
252 | * @param bld Tree builder | |
253 | * @param filter Callback to filter entries | |
254 | */ | |
255 | GIT_EXTERN(void) git_treebuilder_filter(git_treebuilder *bld, int (*filter)(const git_tree_entry *, void *), void *payload); | |
256 | ||
257 | /** | |
258 | * Write the contents of the tree builder as a tree object | |
259 | * | |
260 | * The tree builder will be written to the given `repo`, and | |
261 | * it's identifying SHA1 hash will be stored in the `oid` | |
262 | * pointer. | |
263 | * | |
264 | * @param oid Pointer where to store the written OID | |
265 | * @param repo Repository where to store the object | |
266 | * @param bld Tree builder to write | |
d9111722 | 267 | * @return GIT_SUCCESS or an error code |
0ad6efa1 VM |
268 | */ |
269 | GIT_EXTERN(int) git_treebuilder_write(git_oid *oid, git_repository *repo, git_treebuilder *bld); | |
270 | ||
3fa735ca | 271 | /** |
272 | * Retrieve the tree object containing a tree entry, given | |
273 | * a relative path to this tree entry | |
274 | * | |
275 | * The returned tree is owned by the repository and | |
276 | * should be closed with the `git_object_close` method. | |
277 | * | |
278 | * @param parent_out Pointer where to store the parent tree | |
279 | * @param root A previously loaded tree which will be the root of the relative path | |
280 | * @param treeentry_path Path to the tree entry from which to extract the last tree object | |
281 | * @return GIT_SUCCESS on success; GIT_ENOTFOUND if the path does not lead to an | |
282 | * entry, GIT_EINVALIDPATH or an error code | |
283 | */ | |
284 | GIT_EXTERN(int) git_tree_frompath(git_tree **parent_out, git_tree *root, const char *treeentry_path); | |
225fe215 VM |
285 | /** @} */ |
286 | GIT_END_DECL | |
287 | #endif |