include/git2/tree.h

   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  * @return 0 or an error code
 338  */
 339 GIT_EXTERN(int) git_treebuilder_remove(
 340         git_treebuilder *bld, const char *filename);
 341
 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  */
 349 typedef int GIT_CALLBACK(git_treebuilder_filter_cb)(
 350         const git_tree_entry *entry, void *payload);
 351
 352 /**
 353  * Selectively remove entries in the tree
 354  *
 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).
 358  *
 359  * @param bld Tree builder
 360  * @param filter Callback to filter entries
 361  * @param payload Extra data to pass to filter callback
 362  * @return 0 on success, non-zero callback return value, or error code
 363  */
 364 GIT_EXTERN(int) git_treebuilder_filter(
 365         git_treebuilder *bld,
 366         git_treebuilder_filter_cb filter,
 367         void *payload);
 368
 369 /**
 370  * Write the contents of the tree builder as a tree object
 371  *
 372  * The tree builder will be written to the given `repo`, and its
 373  * identifying SHA1 hash will be stored in the `id` pointer.
 374  *
 375  * @param id Pointer to store the OID of the newly written tree
 376  * @param bld Tree builder to write
 377  * @return 0 or an error code
 378  */
 379 GIT_EXTERN(int) git_treebuilder_write(
 380         git_oid *id, git_treebuilder *bld);
 381
 382 /** Callback for the tree traversal method */
 383 typedef int GIT_CALLBACK(git_treewalk_cb)(
 384         const char *root, const git_tree_entry *entry, void *payload);
 385
 386 /** Tree traversal modes */
 387 typedef enum {
 388         GIT_TREEWALK_PRE = 0, /* Pre-order */
 389         GIT_TREEWALK_POST = 1, /* Post-order */
 390 } git_treewalk_mode;
 391
 392 /**
 393  * Traverse the entries in a tree and its subtrees in post or pre order.
 394  *
 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.
 399  *
 400  * If the callback returns a positive value, the passed entry will be
 401  * skipped on the traversal (in pre mode). A negative value stops the walk.
 402  *
 403  * @param tree The tree to walk
 404  * @param mode Traversal mode (pre or post-order)
 405  * @param callback Function to call on each tree entry
 406  * @param payload Opaque pointer to be passed on each callback
 407  * @return 0 or an error code
 408  */
 409 GIT_EXTERN(int) git_tree_walk(
 410         const git_tree *tree,
 411         git_treewalk_mode mode,
 412         git_treewalk_cb callback,
 413         void *payload);
 414
 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
 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
 467  * @return 0 or an error code
 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
 471 /** @} */
 472
 473 GIT_END_DECL
 474 #endif