Build & write custom trees in memory

1 files changed, 111 insertions, 6 deletions

diff --git a/include/git2/tree.h b/include/git2/tree.h
index 60150b309..0caf60a48 100644
--- a/include/git2/tree.h
+++ b/include/git2/tree.h
@@ -93,7 +93,7 @@ GIT_EXTERN(size_t) git_tree_entrycount(git_tree *tree);
  * @param filename the filename of the desired entry
  * @return the tree entry; NULL if not found
  */
-GIT_EXTERN(git_tree_entry *) git_tree_entry_byname(git_tree *tree, const char *filename);
+GIT_EXTERN(const git_tree_entry *) git_tree_entry_byname(git_tree *tree, const char *filename);
 
 /**
  * Lookup a tree entry by its position in the tree
@@ -102,7 +102,7 @@ GIT_EXTERN(git_tree_entry *) git_tree_entry_byname(git_tree *tree, const char *f
  * @param idx the position in the entry list
  * @return the tree entry; NULL if not found
  */
-GIT_EXTERN(git_tree_entry *) git_tree_entry_byindex(git_tree *tree, int idx);
+GIT_EXTERN(const git_tree_entry *) git_tree_entry_byindex(git_tree *tree, int idx);
 
 /**
  * Get the UNIX file attributes of a tree entry
@@ -110,7 +110,7 @@ GIT_EXTERN(git_tree_entry *) git_tree_entry_byindex(git_tree *tree, int idx);
  * @param entry a tree entry
  * @return attributes as an integer
  */
-GIT_EXTERN(unsigned int) git_tree_entry_attributes(git_tree_entry *entry);
+GIT_EXTERN(unsigned int) git_tree_entry_attributes(const git_tree_entry *entry);
 
 /**
  * Get the filename of a tree entry
@@ -118,7 +118,7 @@ GIT_EXTERN(unsigned int) git_tree_entry_attributes(git_tree_entry *entry);
  * @param entry a tree entry
  * @return the name of the file
  */
-GIT_EXTERN(const char *) git_tree_entry_name(git_tree_entry *entry);
+GIT_EXTERN(const char *) git_tree_entry_name(const git_tree_entry *entry);
 
 /**
  * Get the id of the object pointed by the entry
@@ -126,7 +126,7 @@ GIT_EXTERN(const char *) git_tree_entry_name(git_tree_entry *entry);
  * @param entry a tree entry
  * @return the oid of the object
  */
-GIT_EXTERN(const git_oid *) git_tree_entry_id(git_tree_entry *entry);
+GIT_EXTERN(const git_oid *) git_tree_entry_id(const git_tree_entry *entry);
 
 /**
  * Convert a tree entry to the git_object it points too.
@@ -136,7 +136,7 @@ GIT_EXTERN(const git_oid *) git_tree_entry_id(git_tree_entry *entry);
  * @param entry a tree entry
  * @return 0 on success; error code otherwise
  */
-GIT_EXTERN(int) git_tree_entry_2object(git_object **object_out, git_repository *repo, git_tree_entry *entry);
+GIT_EXTERN(int) git_tree_entry_2object(git_object **object_out, git_repository *repo, const git_tree_entry *entry);
 
 /**
  * Write a tree to the ODB from the index file
@@ -156,6 +156,111 @@ GIT_EXTERN(int) git_tree_entry_2object(git_object **object_out, git_repository *
  */
 GIT_EXTERN(int) git_tree_create_fromindex(git_oid *oid, git_index *index);
 
+/**
+ * Create a new tree builder.
+ *
+ * The tree builder can be used to create or modify
+ * trees in memory and write them as tree objects to the
+ * database.
+ *
+ * If the `source` parameter is not NULL, the tree builder
+ * will be initialized with the entries of the given tree.
+ * 
+ * If the `source` parameter is NULL, the tree builder will
+ * have no entries and will have to be filled manually.
+ *
+ * @param builder_p Pointer where to store the tree builder
+ * @param source Source tree to initialize the builder (optional)
+ * @return 0 on sucess; error code otherwise
+ */
+GIT_EXTERN(int) git_treebuilder_create(git_treebuilder **builder_p, const git_tree *source);
+
+/**
+ * Clear all the entires in the builder
+ *
+ * @param bld Builder to clear
+ */
+GIT_EXTERN(void) git_treebuilder_clear(git_treebuilder *bld);
+
+/**
+ * Free a tree builder
+ *
+ * This will clear all the entries and free to builder.
+ * Failing to free the builder after you're done using it
+ * will result in a memory leak
+ *
+ * @param bld Builder to free
+ */
+GIT_EXTERN(void) git_treebuilder_free(git_treebuilder *bld);
+
+/**
+ * Get an entry from the builder from its filename
+ *
+ * The returned entry is owned by the builder and should
+ * not be freed manually.
+ *
+ * @param bld Tree builder
+ * @param filename Name of the entry
+ * @return pointer to the entry; NULL if not found
+ */
+GIT_EXTERN(const git_tree_entry *) git_treebuilder_get(git_treebuilder *bld, const char *filename);
+
+/**
+ * Add or update an entry to the builder
+ *
+ * Insert a new entry for `filename` in the builder with the
+ * given attributes.
+ *
+ * if an entry named `filename` already exists, its attributes
+ * will be updated with the given ones.
+ *
+ * The optional pointer `entry_out` can be used to retrieve a
+ * pointer to the newly created/updated entry.
+ *
+ * @param entry_out Pointer to store the entry (optional)
+ * @param bld Tree builder
+ * @param filename Filename of the entry
+ * @param id SHA1 oid of the entry
+ * @param attributes Folder attributes of the entry
+ * @return 0 on success; error code otherwise
+ */
+GIT_EXTERN(int) git_treebuilder_insert(git_tree_entry **entry_out, git_treebuilder *bld, const char *filename, const git_oid *id, unsigned int attributes);
+
+/**
+ * Remove an entry from the builder by its filename
+ *
+ * @param bld Tree builder
+ * @param filename Filename of the entry to remove
+ */
+GIT_EXTERN(int) git_treebuilder_remove(git_treebuilder *bld, const char *filename);
+
+/**
+ * Filter the entries in the tree
+ *
+ * The `filter` callback will be called for each entry
+ * in the tree with a pointer to the entry and the
+ * provided `payload`: if the callback returns 1, the
+ * entry will be filtered (removed from the builder).
+ *
+ * @param bld Tree builder
+ * @param filter Callback to filter entries
+ */
+GIT_EXTERN(void) git_treebuilder_filter(git_treebuilder *bld, int (*filter)(const git_tree_entry *, void *), void *payload);
+
+/**
+ * Write the contents of the tree builder as a tree object
+ *
+ * The tree builder will be written to the given `repo`, and
+ * it's identifying SHA1 hash will be stored in the `oid`
+ * pointer.
+ *
+ * @param oid Pointer where to store the written OID
+ * @param repo Repository where to store the object
+ * @param bld Tree builder to write
+ * @return 0 on success; error code otherwise
+ */
+GIT_EXTERN(int) git_treebuilder_write(git_oid *oid, git_repository *repo, git_treebuilder *bld);
+
 /** @} */
 GIT_END_DECL
 #endif