/*

 * Copyright (C) the libgit2 contributors. All rights reserved.

 *

 * 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_git_branch_h__

#define INCLUDE_git_branch_h__

#include "common.h"

#include "oid.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.

 *

 * The returned reference must be freed by the user.

 *

 * The branch name will be checked for validity.

 * See `git_tag_create()` for rules about valid names.

 *

 * @param out Pointer where to store the underlying reference.

 *

 * @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 Commit to which this branch should point. This object

 * must belong to the given `repo`.

 *

 * @param force Overwrite existing branch.

 *

 * @return 0, GIT_EINVALIDSPEC 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_reference **out,

	git_repository *repo,

	const char *branch_name,

	const git_commit *target,

	int force);

/**

 * Create a new branch pointing at a target commit

 *

 * This behaves like `git_branch_create()` but takes an annotated

 * commit, which lets you specify which extended sha syntax string was

 * specified by a user, allowing for more exact reflog messages.

 *

 * See the documentation for `git_branch_create()`.

 *

 * @see git_branch_create

 */

GIT_EXTERN(int) git_branch_create_from_annotated(

	git_reference **ref_out,

	git_repository *repository,

	const char *branch_name,

	const git_annotated_commit *commit,

	int force);

/**

 * Delete an existing branch reference.

 *

 * If the branch is successfully deleted, the passed reference

 * object will be invalidated. The reference must be freed manually

 * by the user.

 *

 * @param branch A valid reference representing a branch

 * @return 0 on success, or an error code.

 */

GIT_EXTERN(int) git_branch_delete(git_reference *branch);

/** Iterator type for branches */

typedef struct git_branch_iterator git_branch_iterator;

/**

 * Create an iterator which loops over the requested branches.

 *

 * @param out the iterator

 * @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 GIT_BRANCH_ALL.

 *

 * @return 0 on success  or an error code

 */

GIT_EXTERN(int) git_branch_iterator_new(

	git_branch_iterator **out,

	git_repository *repo,

	git_branch_t list_flags);

/**

 * Retrieve the next branch from the iterator

 *

 * @param out the reference

 * @param out_type the type of branch (local or remote-tracking)

 * @param iter the branch iterator

 * @return 0 on success, GIT_ITEROVER if there are no more branches or an error code.

 */

GIT_EXTERN(int) git_branch_next(git_reference **out, git_branch_t *out_type, git_branch_iterator *iter);

/**

 * Free a branch iterator

 *

 * @param iter the iterator to free

 */

GIT_EXTERN(void) git_branch_iterator_free(git_branch_iterator *iter);

/**

 * Move/rename an existing local branch reference.

 *

 * The new branch name will be checked for validity.

 * See `git_tag_create()` for rules about valid names.

 *

 * @param branch Current underlying reference of the branch.

 *

 * @param new_branch_name Target name of the branch once the move

 * is performed; this name is validated for consistency.

 *

 * @param force Overwrite existing branch.

 *

 * @return 0 on success, GIT_EINVALIDSPEC or an error code.

 */

GIT_EXTERN(int) git_branch_move(

	git_reference **out,

	git_reference *branch,

	const char *new_branch_name,

	int force);

/**

 * Lookup a branch by its name in a repository.

 *

 * The generated reference must be freed by the user.

 *

 * The branch name will be checked for validity.

 * See `git_tag_create()` for rules about valid names.

 *

 * @param out pointer to the looked-up branch reference

 *

 * @param repo the repository to look up the branch

 *

 * @param branch_name Name of the branch to be looked-up;

 * 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 0 on success; GIT_ENOTFOUND when no matching branch

 * exists, GIT_EINVALIDSPEC, otherwise an error code.

 */

GIT_EXTERN(int) git_branch_lookup(

	git_reference **out,

	git_repository *repo,

	const char *branch_name,

	git_branch_t branch_type);

/**

 * Return the name of the given local or remote branch.

 *

 * The name of the branch matches the definition of the name

 * for git_branch_lookup. That is, if the returned name is given

 * to git_branch_lookup() then the reference is returned that

 * was given to this function.

 *

 * @param out where the pointer of branch name is stored;

 * this is valid as long as the ref is not freed.

 * @param ref the reference ideally pointing to a branch

 *

 * @return 0 on success; otherwise an error code (e.g., if the

 *  ref is no local or remote branch).

 */

GIT_EXTERN(int) git_branch_name(

		const char **out,

		const git_reference *ref);

/**

 * Return the reference supporting the remote tracking branch,

 * given a local branch reference.

 *

 * @param out Pointer where to store the retrieved

 * reference.

 *

 * @param branch Current underlying reference of the branch.

 *

 * @return 0 on success; GIT_ENOTFOUND when no remote tracking

 * reference exists, otherwise an error code.

 */

GIT_EXTERN(int) git_branch_upstream(

	git_reference **out,

	const git_reference *branch);

/**

 * Set the upstream configuration for a given local branch

 *

 * @param branch the branch to configure

 *

 * @param upstream_name remote-tracking or local branch to set as

 * upstream. Pass NULL to unset.

 *

 * @return 0 or an error code

 */

GIT_EXTERN(int) git_branch_set_upstream(git_reference *branch, const char *upstream_name);

/**

 * Return the name of the reference supporting the remote tracking branch,

 * given the name of a local branch reference.

 *

 * @param out Pointer to the user-allocated git_buf which will be

 * filled with the name of the reference.

 *

 * @param repo the repository where the branches live

 *

 * @param refname reference name of the local branch.

 *

 * @return 0, GIT_ENOTFOUND when no remote tracking reference exists,

 *     otherwise an error code.

 */

GIT_EXTERN(int) git_branch_upstream_name(

	git_buf *out,

	git_repository *repo,

	const char *refname);

/**

 * Determine if the current local branch is pointed at by HEAD.

 *

 * @param branch Current underlying reference of the branch.

 *

 * @return 1 if HEAD points at the branch, 0 if it isn't,

 * error code otherwise.

 */

GIT_EXTERN(int) git_branch_is_head(

	const git_reference *branch);

/**

 * Determine if the current branch is checked out in any linked

 * repository.

 *

 * @param branch Reference to the branch.

 *

 * @return 1 if branch is checked out, 0 if it isn't,

 * error code otherwise.

 */

GIT_EXTERN(int) git_branch_is_checked_out(

	const git_reference *branch);

/**

 * Return the name of remote that the remote tracking branch belongs to.

 *

 * @param out Pointer to the user-allocated git_buf which will be filled with the name of the remote.

 *

 * @param repo The repository where the branch lives.

 *

 * @param canonical_branch_name name of the remote tracking branch.

 *

 * @return 0, GIT_ENOTFOUND

 *     when no remote matching remote was found,

 *     GIT_EAMBIGUOUS when the branch maps to several remotes,

 *     otherwise an error code.

 */

GIT_EXTERN(int) git_branch_remote_name(

	git_buf *out,

	git_repository *repo,

	const char *canonical_branch_name);

/**

 * Retrieve the name fo the upstream remote of a local branch

 *

 * @param buf the buffer into which to write the name

 * @param repo the repository in which to look

 * @param refname the full name of the branch

 * @return 0 or an error code

 */

 GIT_EXTERN(int) git_branch_upstream_remote(git_buf *buf, git_repository *repo, const char *refname);

/** @} */

GIT_END_DECL

#endif