1 /* 2 * Copyright (C) the libgit2 contributors. All rights reserved. 3 * 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. 6 */ 7 #ifndef INCLUDE_git_tree_h__ 8 #define INCLUDE_git_tree_h__ 9 10 #include "common.h" 11 #include "types.h" 12 #include "oid.h" 13 #include "object.h" 14 15 /** 16 * @file git2/tree.h 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 24 /** 25 * Lookup a tree object from the repository. 26 * 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. 30 * @return 0 or an error code 31 */ 32 GIT_EXTERN(int) git_tree_lookup( 33 git_tree **out, git_repository *repo, const git_oid *id); 34 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 out 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 45 * @return 0 or an error code 46 */ 47 GIT_EXTERN(int) git_tree_lookup_prefix( 48 git_tree **out, 49 git_repository *repo, 50 const git_oid *id, 51 size_t len); 52 53 /** 54 * Close an open tree 55 * 56 * You can no longer use the git_tree pointer after this call. 57 * 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. 60 * 61 * @param tree The tree to close 62 */ 63 GIT_EXTERN(void) git_tree_free(git_tree *tree); 64 65 /** 66 * Get the id of a tree. 67 * 68 * @param tree a previously loaded tree. 69 * @return object identity for the tree. 70 */ 71 GIT_EXTERN(const git_oid *) git_tree_id(const git_tree *tree); 72 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 81 /** 82 * Get the number of entries listed in a tree 83 * 84 * @param tree a previously loaded tree. 85 * @return the number of entries in the tree 86 */ 87 GIT_EXTERN(size_t) git_tree_entrycount(const git_tree *tree); 88 89 /** 90 * Lookup a tree entry by its filename 91 * 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 * 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 */ 99 GIT_EXTERN(const git_tree_entry *) git_tree_entry_byname( 100 const git_tree *tree, const char *filename); 101 102 /** 103 * Lookup a tree entry by its position in the tree 104 * 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 * 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 */ 112 GIT_EXTERN(const git_tree_entry *) git_tree_entry_byindex( 113 const git_tree *tree, size_t idx); 114 115 /** 116 * Lookup a tree entry by SHA value. 117 * 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 * 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 id the sha being looked for 125 * @return the tree entry; NULL if not found 126 */ 127 GIT_EXTERN(const git_tree_entry *) git_tree_entry_byid( 128 const git_tree *tree, const git_oid *id); 129 130 /** 131 * Retrieve a tree entry contained in a tree or in any of its subtrees, 132 * given its relative path. 133 * 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 path Path to the contained entry 140 * @return 0 on success; GIT_ENOTFOUND if the path does not exist 141 */ 142 GIT_EXTERN(int) git_tree_entry_bypath( 143 git_tree_entry **out, 144 const 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 dest pointer where to store the copy 154 * @param source tree entry to duplicate 155 * @return 0 or an error code 156 */ 157 GIT_EXTERN(int) git_tree_entry_dup(git_tree_entry **dest, const git_tree_entry *source); 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); 169 170 /** 171 * Get the filename of a tree entry 172 * 173 * @param entry a tree entry 174 * @return the name of the file 175 */ 176 GIT_EXTERN(const char *) git_tree_entry_name(const git_tree_entry *entry); 177 178 /** 179 * Get the id of the object pointed by the entry 180 * 181 * @param entry a tree entry 182 * @return the oid of the object 183 */ 184 GIT_EXTERN(const git_oid *) git_tree_entry_id(const git_tree_entry *entry); 185 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_object_t) git_tree_entry_type(const git_tree_entry *entry); 193 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 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); 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 222 /** 223 * Convert a tree entry to the git_object it points to. 224 * 225 * You must call `git_object_free()` on the object when you are done with it. 226 * 227 * @param object_out pointer to the converted object 228 * @param repo repository where to lookup the pointed object 229 * @param entry a tree entry 230 * @return 0 or an error code 231 */ 232 GIT_EXTERN(int) git_tree_entry_to_object( 233 git_object **object_out, 234 git_repository *repo, 235 const git_tree_entry *entry); 236 237 /** 238 * Create a new tree builder. 239 * 240 * The tree builder can be used to create or modify trees in memory and 241 * write them as tree objects to the database. 242 * 243 * If the `source` parameter is not NULL, the tree builder will be 244 * initialized with the entries of the given tree. 245 * 246 * If the `source` parameter is NULL, the tree builder will start with no 247 * entries and will have to be filled manually. 248 * 249 * @param out Pointer where to store the tree builder 250 * @param repo Repository in which to store the object 251 * @param source Source tree to initialize the builder (optional) 252 * @return 0 on success; error code otherwise 253 */ 254 GIT_EXTERN(int) git_treebuilder_new( 255 git_treebuilder **out, git_repository *repo, const git_tree *source); 256 257 /** 258 * Clear all the entires in the builder 259 * 260 * @param bld Builder to clear 261 * @return 0 on success; error code otherwise 262 */ 263 GIT_EXTERN(int) git_treebuilder_clear(git_treebuilder *bld); 264 265 /** 266 * Get the number of entries listed in a treebuilder 267 * 268 * @param bld a previously loaded treebuilder. 269 * @return the number of entries in the treebuilder 270 */ 271 GIT_EXTERN(size_t) git_treebuilder_entrycount(git_treebuilder *bld); 272 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 */ 294 GIT_EXTERN(const git_tree_entry *) git_treebuilder_get( 295 git_treebuilder *bld, const char *filename); 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 * 303 * If an entry named `filename` already exists, its attributes 304 * will be updated with the given ones. 305 * 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. 310 * 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. 315 * 316 * @param out Pointer to store the entry (optional) 317 * @param bld Tree builder 318 * @param filename Filename of the entry 319 * @param id SHA1 oid of the entry 320 * @param filemode Folder attributes of the entry. This parameter must 321 * be valued with one of the following entries: 0040000, 0100644, 322 * 0100755, 0120000 or 0160000. 323 * @return 0 or an error code 324 */ 325 GIT_EXTERN(int) git_treebuilder_insert( 326 const git_tree_entry **out, 327 git_treebuilder *bld, 328 const char *filename, 329 const git_oid *id, 330 git_filemode_t filemode); 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 337 */ 338 GIT_EXTERN(int) git_treebuilder_remove( 339 git_treebuilder *bld, const char *filename); 340 341 /** 342 * Callback for git_treebuilder_filter 343 * 344 * The return value is treated as a boolean, with zero indicating that the 345 * entry should be left alone and any non-zero value meaning that the 346 * entry should be removed from the treebuilder list (i.e. filtered out). 347 */ 348 typedef int GIT_CALLBACK(git_treebuilder_filter_cb)( 349 const git_tree_entry *entry, void *payload); 350 351 /** 352 * Selectively remove entries in the tree 353 * 354 * The `filter` callback will be called for each entry in the tree with a 355 * pointer to the entry and the provided `payload`; if the callback returns 356 * non-zero, the entry will be filtered (removed from the builder). 357 * 358 * @param bld Tree builder 359 * @param filter Callback to filter entries 360 * @param payload Extra data to pass to filter callback 361 * @return 0 on success, non-zero callback return value, or error code 362 */ 363 GIT_EXTERN(int) git_treebuilder_filter( 364 git_treebuilder *bld, 365 git_treebuilder_filter_cb filter, 366 void *payload); 367 368 /** 369 * Write the contents of the tree builder as a tree object 370 * 371 * The tree builder will be written to the given `repo`, and its 372 * identifying SHA1 hash will be stored in the `id` pointer. 373 * 374 * @param id Pointer to store the OID of the newly written tree 375 * @param bld Tree builder to write 376 * @return 0 or an error code 377 */ 378 GIT_EXTERN(int) git_treebuilder_write( 379 git_oid *id, git_treebuilder *bld); 380 381 /** Callback for the tree traversal method */ 382 typedef int GIT_CALLBACK(git_treewalk_cb)( 383 const char *root, const git_tree_entry *entry, void *payload); 384 385 /** Tree traversal modes */ 386 typedef enum { 387 GIT_TREEWALK_PRE = 0, /* Pre-order */ 388 GIT_TREEWALK_POST = 1, /* Post-order */ 389 } git_treewalk_mode; 390 391 /** 392 * Traverse the entries in a tree and its subtrees in post or pre order. 393 * 394 * The entries will be traversed in the specified order, children subtrees 395 * will be automatically loaded as required, and the `callback` will be 396 * called once per entry with the current (relative) root for the entry and 397 * the entry data itself. 398 * 399 * If the callback returns a positive value, the passed entry will be 400 * skipped on the traversal (in pre mode). A negative value stops the walk. 401 * 402 * @param tree The tree to walk 403 * @param mode Traversal mode (pre or post-order) 404 * @param callback Function to call on each tree entry 405 * @param payload Opaque pointer to be passed on each callback 406 * @return 0 or an error code 407 */ 408 GIT_EXTERN(int) git_tree_walk( 409 const git_tree *tree, 410 git_treewalk_mode mode, 411 git_treewalk_cb callback, 412 void *payload); 413 414 /** 415 * Create an in-memory copy of a tree. The copy must be explicitly 416 * free'd or it will leak. 417 * 418 * @param out Pointer to store the copy of the tree 419 * @param source Original tree to copy 420 */ 421 GIT_EXTERN(int) git_tree_dup(git_tree **out, git_tree *source); 422 423 /** 424 * The kind of update to perform 425 */ 426 typedef enum { 427 /** Update or insert an entry at the specified path */ 428 GIT_TREE_UPDATE_UPSERT, 429 /** Remove an entry from the specified path */ 430 GIT_TREE_UPDATE_REMOVE, 431 } git_tree_update_t; 432 433 /** 434 * An action to perform during the update of a tree 435 */ 436 typedef struct { 437 /** Update action. If it's an removal, only the path is looked at */ 438 git_tree_update_t action; 439 /** The entry's id */ 440 git_oid id; 441 /** The filemode/kind of object */ 442 git_filemode_t filemode; 443 /** The full path from the root tree */ 444 const char *path; 445 } git_tree_update; 446 447 /** 448 * Create a tree based on another one with the specified modifications 449 * 450 * Given the `baseline` perform the changes described in the list of 451 * `updates` and create a new tree. 452 * 453 * This function is optimized for common file/directory addition, removal and 454 * replacement in trees. It is much more efficient than reading the tree into a 455 * `git_index` and modifying that, but in exchange it is not as flexible. 456 * 457 * Deleting and adding the same entry is undefined behaviour, changing 458 * a tree to a blob or viceversa is not supported. 459 * 460 * @param out id of the new tree 461 * @param repo the repository in which to create the tree, must be the 462 * same as for `baseline` 463 * @param baseline the tree to base these changes on 464 * @param nupdates the number of elements in the update list 465 * @param updates the list of updates to perform 466 */ 467 GIT_EXTERN(int) git_tree_create_updated(git_oid *out, git_repository *repo, git_tree *baseline, size_t nupdates, const git_tree_update *updates); 468 469 /** @} */ 470 471 GIT_END_DECL 472 #endif 473