include/git2/refs.h

/*
 * Copyright (C) 2009-2012 the libgit2 contributors
 *
 * 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_refs_h__
#define INCLUDE_git_refs_h__

#include "common.h"
#include "types.h"
#include "oid.h"
#include "strarray.h"

/**
 * @file git2/refs.h
 * @brief Git reference management routines
 * @defgroup git_reference Git reference management routines
 * @ingroup Git
 * @{
 */
GIT_BEGIN_DECL

/**
 * Lookup a reference by its name in a repository.
 *
 * The generated reference must be freed by the user.
 *
 * @param reference_out pointer to the looked-up reference
 * @param repo the repository to look up the reference
 * @param name the long name for the reference (e.g. HEAD, ref/heads/master, refs/tags/v0.1.0, ...)
 * @return 0 or an error code
 */
GIT_EXTERN(int) git_reference_lookup(git_reference **reference_out, git_repository *repo, const char *name);

/**
 * Lookup a reference by name and resolve immediately to OID.
 *
 * @param oid Pointer to oid to be filled in
 * @param repo The repository in which to look up the reference
 * @param name The long name for the reference
 * @return 0 on success, -1 if name could not be resolved
 */
GIT_EXTERN(int) git_reference_name_to_oid(
	git_oid *out, git_repository *repo, const char *name);

/**
 * Create a new symbolic reference.
 *
 * The reference will be created in the repository and written
 * to the disk.
 *
 * The generated reference must be freed by the user.
 *
 * If `force` is true and there already exists a reference
 * with the same name, it will be overwritten.
 *
 * @param ref_out Pointer to the newly created reference
 * @param repo Repository where that reference will live
 * @param name The name of the reference
 * @param target The target of the reference
 * @param force Overwrite existing references
 * @return 0 or an error code
 */
GIT_EXTERN(int) git_reference_create_symbolic(git_reference **ref_out, git_repository *repo, const char *name, const char *target, int force);

/**
 * Create a new object id reference.
 *
 * The reference will be created in the repository and written
 * to the disk.
 *
 * The generated reference must be freed by the user.
 *
 * If `force` is true and there already exists a reference
 * with the same name, it will be overwritten.
 *
 * @param ref_out Pointer to the newly created reference
 * @param repo Repository where that reference will live
 * @param name The name of the reference
 * @param id The object id pointed to by the reference.
 * @param force Overwrite existing references
 * @return 0 or an error code
 */
GIT_EXTERN(int) git_reference_create_oid(git_reference **ref_out, git_repository *repo, const char *name, const git_oid *id, int force);

/**
 * Get the OID pointed to by a reference.
 *
 * Only available if the reference is direct (i.e. not symbolic)
 *
 * @param ref The reference
 * @return a pointer to the oid if available, NULL otherwise
 */
GIT_EXTERN(const git_oid *) git_reference_oid(git_reference *ref);

/**
 * Get full name to the reference pointed by this reference
 *
 * Only available if the reference is symbolic
 *
 * @param ref The reference
 * @return a pointer to the name if available, NULL otherwise
 */
GIT_EXTERN(const char *) git_reference_target(git_reference *ref);

/**
 * Get the type of a reference
 *
 * Either direct (GIT_REF_OID) or symbolic (GIT_REF_SYMBOLIC)
 *
 * @param ref The reference
 * @return the type
 */
GIT_EXTERN(git_ref_t) git_reference_type(git_reference *ref);

/**
 * Get the full name of a reference
 *
 * @param ref The reference
 * @return the full name for the ref
 */
GIT_EXTERN(const char *) git_reference_name(git_reference *ref);

/**
 * Resolve a symbolic reference
 *
 * This method iteratively peels a symbolic reference
 * until it resolves to a direct reference to an OID.
 *
 * The peeled reference is returned in the `resolved_ref`
 * argument, and must be freed manually once it's no longer
 * needed.
 *
 * If a direct reference is passed as an argument,
 * a copy of that reference is returned. This copy must
 * be manually freed too.
 *
 * @param resolved_ref Pointer to the peeled reference
 * @param ref The reference
 * @return 0 or an error code
 */
GIT_EXTERN(int) git_reference_resolve(git_reference **resolved_ref, git_reference *ref);

/**
 * Get the repository where a reference resides
 *
 * @param ref The reference
 * @return a pointer to the repo
 */
GIT_EXTERN(git_repository *) git_reference_owner(git_reference *ref);

/**
 * Set the symbolic target of a reference.
 *
 * The reference must be a symbolic reference, otherwise
 * this method will fail.
 *
 * The reference will be automatically updated in
 * memory and on disk.
 *
 * @param ref The reference
 * @param target The new target for the reference
 * @return 0 or an error code
 */
GIT_EXTERN(int) git_reference_set_target(git_reference *ref, const char *target);

/**
 * Set the OID target of a reference.
 *
 * The reference must be a direct reference, otherwise
 * this method will fail.
 *
 * The reference will be automatically updated in
 * memory and on disk.
 *
 * @param ref The reference
 * @param id The new target OID for the reference
 * @return 0 or an error code
 */
GIT_EXTERN(int) git_reference_set_oid(git_reference *ref, const git_oid *id);

/**
 * Rename an existing reference
 *
 * This method works for both direct and symbolic references.
 * The new name will be checked for validity and may be
 * modified into a normalized form.
 *
 * The given git_reference will be updated in place.
 *
 * The reference will be immediately renamed in-memory
 * and on disk.
 *
 * If the `force` flag is not enabled, and there's already
 * a reference with the given name, the renaming will fail.
 *
 * IMPORTANT:
 * The user needs to write a proper reflog entry if the
 * reflog is enabled for the repository. We only rename
 * the reflog if it exists.
 *
 * @param ref The reference to rename
 * @param new_name The new name for the reference
 * @param force Overwrite an existing reference
 * @return 0 or an error code
 *
 */
GIT_EXTERN(int) git_reference_rename(git_reference *ref, const char *new_name, int force);

/**
 * Delete an existing reference
 *
 * This method works for both direct and symbolic references.
 *
 * The reference will be immediately removed on disk and from
 * memory. The given reference pointer will no longer be valid.
 *
 * @param ref The reference to remove
 * @return 0 or an error code
 */
GIT_EXTERN(int) git_reference_delete(git_reference *ref);

/**
 * Pack all the loose references in the repository
 *
 * This method will load into the cache all the loose
 * references on the repository and update the
 * `packed-refs` file with them.
 *
 * Once the `packed-refs` file has been written properly,
 * the loose references will be removed from disk.
 *
 * @param repo Repository where the loose refs will be packed
 * @return 0 or an error code
 */
GIT_EXTERN(int) git_reference_packall(git_repository *repo);

/**
 * Fill a list with all the references that can be found
 * in a repository.
 *
 * The listed references may be filtered by type, or using
 * a bitwise OR of several types. Use the magic value
 * `GIT_REF_LISTALL` to obtain all references, including
 * packed ones.
 *
 * The string array will be filled with the names of all
 * references; these values are owned by the user and
 * should be free'd manually when no longer needed, using
 * `git_strarray_free`.
 *
 * @param array Pointer to a git_strarray structure where
 *		the reference names will be stored
 * @param repo Repository where to find the refs
 * @param list_flags Filtering flags for the reference
 *		listing.
 * @return 0 or an error code
 */
GIT_EXTERN(int) git_reference_list(git_strarray *array, git_repository *repo, unsigned int list_flags);

/**
 * Perform an operation on each reference in the repository
 *
 * The processed references may be filtered by type, or using
 * a bitwise OR of several types. Use the magic value
 * `GIT_REF_LISTALL` to obtain all references, including
 * packed ones.
 *
 * The `callback` function will be called for each of the references
 * in the repository, and will receive the name of the reference and
 * the `payload` value passed to this method.  Returning a non-zero
 * value from the callback will terminate the iteration.
 *
 * @param repo Repository where to find the refs
 * @param list_flags Filtering flags for the reference
 *		listing.
 * @param callback Function which will be called for every listed ref
 * @param payload Additional data to pass to the callback
 * @return 0 on success, GIT_EUSER on non-zero callback, or error code
 */
GIT_EXTERN(int) git_reference_foreach(git_repository *repo, unsigned int list_flags, int (*callback)(const char *, void *), void *payload);

/**
 * Check if a reference has been loaded from a packfile
 *
 * @param ref A git reference
 * @return 0 in case it's not packed; 1 otherwise
 */
GIT_EXTERN(int) git_reference_is_packed(git_reference *ref);

/**
 * Reload a reference from disk
 *
 * Reference pointers may become outdated if the Git
 * repository is accessed simultaneously by other clients
 * while the library is open.
 *
 * This method forces a reload of the reference from disk,
 * to ensure that the provided information is still
 * reliable.
 *
 * If the reload fails (e.g. the reference no longer exists
 * on disk, or has become corrupted), an error code will be
 * returned and the reference pointer will be invalidated.
 *
 * @param ref The reference to reload
 * @return 0 on success, or an error code
 */
GIT_EXTERN(int) git_reference_reload(git_reference *ref);

/**
 * Free the given reference
 *
 * @param ref git_reference
 */
GIT_EXTERN(void) git_reference_free(git_reference *ref);

/**
 * Compare two references.
 *
 * @param ref1 The first git_reference
 * @param ref2 The second git_reference
 * @return 0 if the same, else a stable but meaningless ordering.
 */
GIT_EXTERN(int) git_reference_cmp(git_reference *ref1, git_reference *ref2);

/**
 * Loop over all the references and issue a callback for each one
 * which name matches the given glob pattern.
 *
 * The processed references may be filtered by type, or using
 * a bitwise OR of several types. Use the magic value
 * `GIT_REF_LISTALL` to obtain all references, including
 * packed ones.
 *
 * @param repo Repository where to find the references.
 *
 * @param glob Glob pattern references should match.
 *
 * @param list_flags Filtering flags for the reference
 * listing.
 *
 * @param callback Callback to invoke per found reference.
 *
 * @param payload Extra parameter to callback function.
 *
 * @return 0 or an error code.
 */
GIT_EXTERN(int) git_reference_foreach_glob(
		git_repository *repo,
		const char *glob,
		unsigned int list_flags,
		int (*callback)(
			const char *reference_name,
			void *payload),
		void *payload
);

/**
 * Check if a reflog exists for the specified reference.
 *
 * @param ref A git reference
 *
 * @return 0 when no reflog can be found, 1 when it exists;
 * otherwise an error code.
 */
GIT_EXTERN(int) git_reference_has_log(git_reference *ref);

/**
 * Check if a reference is a local branch.
 *
 * @param ref A git reference
 *
 * @return 1 when the reference lives in the refs/heads
 * namespace; 0 otherwise.
 */
GIT_EXTERN(int) git_reference_is_branch(git_reference *ref);

/**
 * Check if a reference is a remote tracking branch
 *
 * @param ref A git reference
 *
 * @return 1 when the reference lives in the refs/remotes
 * namespace; 0 otherwise.
 */
GIT_EXTERN(int) git_reference_is_remote(git_reference *ref);

enum {
	GIT_REF_FORMAT_NORMAL = 0,

	/**
	 * Control whether one-level refnames are accepted
	 * (i.e., refnames that do not contain multiple /-separated
	 * components). Those are expected to be written only using
	 * uppercase letters and underscore (FETCH_HEAD, ...)
	 */
	GIT_REF_FORMAT_ALLOW_ONELEVEL = (1 << 0),

	/**
	 * Interpret the provided name as a reference pattern for a
	 * refspec (as used with remote repositories). If this option
	 * is enabled, the name is allowed to contain a single * (<star>)
	 * in place of a one full pathname component
	 * (e.g., foo/<star>/bar but not foo/bar<star>).
	 */
	GIT_REF_FORMAT_REFSPEC_PATTERN = (1 << 1),
};

/**
 * Normalize the reference name by removing any leading
 * slash (/) characters and collapsing runs of adjacent slashes
 * between name components into a single slash.
 *
 * Once normalized, if the reference name is valid, it will be
 * returned in the user allocated buffer.
 *
 * @param buffer_out The user allocated buffer where the
 * normalized name will be stored.
 *
 * @param buffer_size buffer_out size
 *
 * @param name name to be checked.
 *
 * @param flags Flags to determine the options to be applied while
 * checking the validatity of the name.
 *
 * @return 0 or an error code.
 */
GIT_EXTERN(int) git_reference_normalize_name(
	char *buffer_out,
	size_t buffer_size,
	const char *name,
	unsigned int flags);

/**
 * Recursively peel an reference until an object of the
 * specified type is met.
 *
 * The retrieved `peeled` object is owned by the repository
 * and should be closed with the `git_object_free` method.
 *
 * If you pass `GIT_OBJ_ANY` as the target type, then the object
 * will be peeled until a non-tag object is met.
 *
 * @param peeled Pointer to the peeled git_object
 * @param ref The reference to be processed
 * @param target_type The type of the requested object
 * @return 0 or an error code
 */
GIT_EXTERN(int) git_reference_peel(
	git_object **out,
	git_reference *ref,
	git_otype type);

/**
 * Ensure the reference name is well-formed.
 *
 * @param refname name to be checked.
 *
 * @return 1 if the reference name is acceptable; 0 if it isn't
 */
GIT_EXTERN(int) git_reference_is_valid_name(
	const char *refname);

/** @} */
GIT_END_DECL
#endif