Add basic branch management API: git_branch_create(), git_branch_delete(), git_branch_list()

1 files changed, 91 insertions, 6 deletions

diff --git a/include/git2/branch.h b/include/git2/branch.h
index 75927e99a..fa1c6f3ec 100644
--- a/include/git2/branch.h
+++ b/include/git2/branch.h
@@ -4,12 +4,97 @@
  * This file is part of libgit2, distributed under the GNU GPL v2 with
  * a Linking Exception. For full terms see the included COPYING file.
  */
-#ifndef INCLUDE_branch_h__
-#define INCLUDE_branch_h__
+#ifndef INCLUDE_git_branch_h__
+#define INCLUDE_git_branch_h__
 
-struct git_branch {
-	char *remote; /* TODO: Make this a git_remote */
-	char *merge;
-};
+#include "common.h"
+#include "types.h"
 
+/**
+ * @file git2/branch.h
+ * @brief Git branch parsing routines
+ * @defgroup git_branch Git branch management
+ * @ingroup Git
+ * @{
+ */
+GIT_BEGIN_DECL
+
+/**
+ * Create a new branch pointing at a target commit
+ *
+ * A new direct reference will be created pointing to
+ * this target commit. If `force` is true and a reference
+ * already exists with the given name, it'll be replaced.
+ *
+ * @param oid_out Pointer where to store the OID of the target commit.
+ *
+ * @param repo Repository where to store the branch.
+ *
+ * @param branch_name Name for the branch; this name is
+ * validated for consistency. It should also not conflict with
+ * an already existing branch name.
+ *
+ * @param target Object to which this branch should point. This object
+ * must belong to the given `repo` and can either be a git_commit or a
+ * git_tag. When a git_tag is being passed, it should be dereferencable
+ * to a git_commit which oid will be used as the target of the branch.
+ *
+ * @param force Overwrite existing branch.
+ *
+ * @return GIT_SUCCESS or an error code.
+ * A proper reference is written in the refs/heads namespace
+ * pointing to the provided target commit.
+ */
+GIT_EXTERN(int) git_branch_create(
+		git_oid *oid_out,
+		git_repository *repo,
+		const char *branch_name,
+		const git_object *target,
+		int force);
+
+/**
+ * Delete an existing branch reference.
+ *
+ * @param repo Repository where lives the branch.
+ *
+ * @param branch_name Name of the branch to be deleted;
+ * this name is validated for consistency.
+ *
+ * @param branch_type Type of the considered branch. This should
+ * be valued with either GIT_BRANCH_LOCAL or GIT_BRANCH_REMOTE.
+ *
+ * @return GIT_SUCCESS on success, GIT_ENOTFOUND if the branch
+ * doesn't exist or an error code.
+ */
+GIT_EXTERN(int) git_branch_delete(
+		git_repository *repo,
+		const char *branch_name,
+		enum git_branch_type branch_type);
+
+/**
+ * Fill a list with all the branches in the Repository
+ *
+ * The string array will be filled with the names of the
+ * matching branches; these values are owned by the user and
+ * should be free'd manually when no longer needed, using
+ * `git_strarray_free`.
+ *
+ * @param branch_names Pointer to a git_strarray structure
+ * where the branch names will be stored.
+ *
+ * @param repo Repository where to find the branches.
+ *
+ * @param list_flags Filtering flags for the branch
+ * listing. Valid values are GIT_BRANCH_LOCAL, GIT_BRANCH_REMOTE
+ * or a combination of the two.
+ *
+ * @return GIT_SUCCESS or an error code.
+ */
+GIT_EXTERN(int) git_branch_list(
+		git_strarray *branch_names,
+		git_repository *repo,
+		unsigned int list_flags);
+
+/** @} */
+GIT_END_DECL
 #endif