* 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_refs_h__
#define INCLUDE_git_refs_h__
* @brief Git reference management routines
* @defgroup git_reference Git reference management routines
* Lookup a reference by name in a repository.
* The returned reference must be freed by the user.
* The name will be checked for validity.
* See `git_reference_symbolic_create()` for rules about valid names.
* @param 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, refs/heads/master, refs/tags/v0.1.0, ...)
* @return 0 on success, GIT_ENOTFOUND, GIT_EINVALIDSPEC or an error code.
GIT_EXTERN(int) git_reference_lookup(git_reference **out, git_repository *repo, const char *name);
* Lookup a reference by name and resolve immediately to OID.
* This function provides a quick way to resolve a reference name straight
* through to the object id that it refers to. This avoids having to
* allocate or free any `git_reference` objects for simple situations.
* The name will be checked for validity.
* See `git_reference_symbolic_create()` for rules about valid names.
* @param out 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 (e.g. HEAD, refs/heads/master, refs/tags/v0.1.0, ...)
* @return 0 on success, GIT_ENOTFOUND, GIT_EINVALIDSPEC or an error code.
GIT_EXTERN(int) git_reference_name_to_id(
git_oid *out, git_repository *repo, const char *name);
* Lookup a reference by DWIMing its short name
* Apply the git precendence rules to the given shorthand to determine
* which reference the user is referring to.
* @param out pointer in which to store the reference
* @param repo the repository in which to look
* @param shorthand the short name for the reference
* @return 0 or an error code
GIT_EXTERN(int) git_reference_dwim(git_reference **out, git_repository *repo, const char *shorthand);
* Conditionally create a new symbolic reference.
* A symbolic reference is a reference name that refers to another
* reference name. If the other name moves, the symbolic name will move,
* too. As a simple example, the "HEAD" reference might refer to
* "refs/heads/master" while on the "master" branch of a repository.
* The symbolic reference will be created in the repository and written to
* the disk. The generated reference object must be freed by the user.
* Valid reference names must follow one of two patterns:
* 1. Top-level names must contain only capital letters and underscores,
* and must begin and end with a letter. (e.g. "HEAD", "ORIG_HEAD").
* 2. Names prefixed with "refs/" can be almost anything. You must avoid
* the characters '~', '^', ':', '\\', '?', '[', and '*', and the
* sequences ".." and "@{" which have special meaning to revparse.
* This function will return an error if a reference already exists with the
* given name unless `force` is true, in which case it will be overwritten.
* The message for the reflog will be ignored if the reference does
* not belong in the standard set (HEAD, branches and remote-tracking
* branches) and it does not have a reflog.
* It will return GIT_EMODIFIED if the reference's value at the time
* of updating does not match the one passed through `current_value`
* (i.e. if the ref has changed since the user read it).
* @param 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
* @param current_value The expected value of the reference when updating
* @param log_message The one line long message to be appended to the reflog
* @return 0 on success, GIT_EEXISTS, GIT_EINVALIDSPEC, GIT_EMODIFIED or an error code
GIT_EXTERN(int) git_reference_symbolic_create_matching(git_reference **out, git_repository *repo, const char *name, const char *target, int force, const char *current_value, const char *log_message);
* Create a new symbolic reference.
* A symbolic reference is a reference name that refers to another
* reference name. If the other name moves, the symbolic name will move,
* too. As a simple example, the "HEAD" reference might refer to
* "refs/heads/master" while on the "master" branch of a repository.
* The symbolic reference will be created in the repository and written to
* the disk. The generated reference object must be freed by the user.
* Valid reference names must follow one of two patterns:
* 1. Top-level names must contain only capital letters and underscores,
* and must begin and end with a letter. (e.g. "HEAD", "ORIG_HEAD").
* 2. Names prefixed with "refs/" can be almost anything. You must avoid
* the characters '~', '^', ':', '\\', '?', '[', and '*', and the
* sequences ".." and "@{" which have special meaning to revparse.
* This function will return an error if a reference already exists with the
* given name unless `force` is true, in which case it will be overwritten.
* The message for the reflog will be ignored if the reference does
* not belong in the standard set (HEAD, branches and remote-tracking
* branches) and it does not have a reflog.
* @param 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
* @param log_message The one line long message to be appended to the reflog
* @return 0 on success, GIT_EEXISTS, GIT_EINVALIDSPEC or an error code
GIT_EXTERN(int) git_reference_symbolic_create(git_reference **out, git_repository *repo, const char *name, const char *target, int force, const char *log_message);
* Create a new direct reference.
* A direct reference (also called an object id reference) refers directly
* to a specific object id (a.k.a. OID or SHA) in the repository. The id
* permanently refers to the object (although the reference itself can be
* moved). For example, in libgit2 the direct ref "refs/tags/v0.17.0"
* refers to OID 5b9fac39d8a76b9139667c26a63e6b3f204b3977.
* The direct reference will be created in the repository and written to
* the disk. The generated reference object must be freed by the user.
* Valid reference names must follow one of two patterns:
* 1. Top-level names must contain only capital letters and underscores,
* and must begin and end with a letter. (e.g. "HEAD", "ORIG_HEAD").
* 2. Names prefixed with "refs/" can be almost anything. You must avoid
* the characters '~', '^', ':', '\\', '?', '[', and '*', and the
* sequences ".." and "@{" which have special meaning to revparse.
* This function will return an error if a reference already exists with the
* given name unless `force` is true, in which case it will be overwritten.
* The message for the reflog will be ignored if the reference does
* not belong in the standard set (HEAD, branches and remote-tracking
* branches) and and it does not have a reflog.
* @param 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
* @param log_message The one line long message to be appended to the reflog
* @return 0 on success, GIT_EEXISTS, GIT_EINVALIDSPEC or an error code
GIT_EXTERN(int) git_reference_create(git_reference **out, git_repository *repo, const char *name, const git_oid *id, int force, const char *log_message);
* Conditionally create new direct reference
* A direct reference (also called an object id reference) refers directly
* to a specific object id (a.k.a. OID or SHA) in the repository. The id
* permanently refers to the object (although the reference itself can be
* moved). For example, in libgit2 the direct ref "refs/tags/v0.17.0"
* refers to OID 5b9fac39d8a76b9139667c26a63e6b3f204b3977.
* The direct reference will be created in the repository and written to
* the disk. The generated reference object must be freed by the user.
* Valid reference names must follow one of two patterns:
* 1. Top-level names must contain only capital letters and underscores,
* and must begin and end with a letter. (e.g. "HEAD", "ORIG_HEAD").
* 2. Names prefixed with "refs/" can be almost anything. You must avoid
* the characters '~', '^', ':', '\\', '?', '[', and '*', and the
* sequences ".." and "@{" which have special meaning to revparse.
* This function will return an error if a reference already exists with the
* given name unless `force` is true, in which case it will be overwritten.
* The message for the reflog will be ignored if the reference does
* not belong in the standard set (HEAD, branches and remote-tracking
* branches) and and it does not have a reflog.
* It will return GIT_EMODIFIED if the reference's value at the time
* of updating does not match the one passed through `current_id`
* (i.e. if the ref has changed since the user read it).
* @param 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
* @param current_id The expected value of the reference at the time of update
* @param log_message The one line long message to be appended to the reflog
* @return 0 on success, GIT_EMODIFIED if the value of the reference
* has changed, GIT_EEXISTS, GIT_EINVALIDSPEC or an error code
GIT_EXTERN(int) git_reference_create_matching(git_reference **out, git_repository *repo, const char *name, const git_oid *id, int force, const git_oid *current_id, const char *log_message);
* Get the OID pointed to by a direct reference.
* Only available if the reference is direct (i.e. an object id reference,
* To find the OID of a symbolic ref, call `git_reference_resolve()` and
* then this function (or maybe use `git_reference_name_to_id()` to
* directly resolve a reference name all the way through to an OID).
* @param ref The reference
* @return a pointer to the oid if available, NULL otherwise
GIT_EXTERN(const git_oid *) git_reference_target(const git_reference *ref);
* Return the peeled OID target of this reference.
* This peeled OID only applies to direct references that point to
* a hard Tag object: it is the result of peeling such Tag.
* @param ref The reference
* @return a pointer to the oid if available, NULL otherwise
GIT_EXTERN(const git_oid *) git_reference_target_peel(const git_reference *ref);
* Get full name to the reference pointed to by a symbolic 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_symbolic_target(const git_reference *ref);
* Get the type of a reference.
* Either direct (GIT_REFERENCE_DIRECT) or symbolic (GIT_REFERENCE_SYMBOLIC)
* @param ref The reference
GIT_EXTERN(git_reference_t) git_reference_type(const git_reference *ref);
* Get the full name of a reference.
* See `git_reference_symbolic_create()` for rules about valid names.
* @param ref The reference
* @return the full name for the ref
GIT_EXTERN(const char *) git_reference_name(const git_reference *ref);
* Resolve a symbolic reference to a direct 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 out Pointer to the peeled reference
* @param ref The reference
* @return 0 or an error code
GIT_EXTERN(int) git_reference_resolve(git_reference **out, const 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(const git_reference *ref);
* Create a new reference with the same name as the given reference but a
* different symbolic target. The reference must be a symbolic reference,
* otherwise this will fail.
* The new reference will be written to disk, overwriting the given reference.
* The target name will be checked for validity.
* See `git_reference_symbolic_create()` for rules about valid names.
* The message for the reflog will be ignored if the reference does
* not belong in the standard set (HEAD, branches and remote-tracking
* branches) and and it does not have a reflog.
* @param out Pointer to the newly created reference
* @param ref The reference
* @param target The new target for the reference
* @param log_message The one line long message to be appended to the reflog
* @return 0 on success, GIT_EINVALIDSPEC or an error code
GIT_EXTERN(int) git_reference_symbolic_set_target(
const char *log_message);
* Conditionally create a new reference with the same name as the given reference but a
* different OID target. The reference must be a direct reference, otherwise
* The new reference will be written to disk, overwriting the given reference.
* @param out Pointer to the newly created reference
* @param ref The reference
* @param id The new target OID for the reference
* @param log_message The one line long message to be appended to the reflog
* @return 0 on success, GIT_EMODIFIED if the value of the reference
* has changed since it was read, or an error code
GIT_EXTERN(int) git_reference_set_target(
const char *log_message);
* Rename an existing reference.
* This method works for both direct and symbolic references.
* The new name will be checked for validity.
* See `git_reference_symbolic_create()` for rules about valid names.
* If the `force` flag is not enabled, and there's already
* a reference with the given name, the renaming will fail.
* 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
* @param log_message The one line long message to be appended to the reflog
* @return 0 on success, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code
GIT_EXTERN(int) git_reference_rename(
const char *log_message);
* Delete an existing reference.
* This method works for both direct and symbolic references. The reference
* will be immediately removed on disk but the memory will not be freed.
* Callers must call `git_reference_free`.
* This function will return an error if the reference has changed
* from the time it was looked up.
* @param ref The reference to remove
* @return 0, GIT_EMODIFIED or an error code
GIT_EXTERN(int) git_reference_delete(git_reference *ref);
* Delete an existing reference by name
* This method removes the named reference from the repository without
* looking at its old value.
* @param name The reference to remove
* @return 0 or an error code
GIT_EXTERN(int) git_reference_remove(git_repository *repo, const char *name);
* Fill a list with all the references that can be found in a repository.
* 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
* @return 0 or an error code
GIT_EXTERN(int) git_reference_list(git_strarray *array, git_repository *repo);
* Callback used to iterate over references
* @see git_reference_foreach
* @param reference The reference object
* @param payload Payload passed to git_reference_foreach
* @return non-zero to terminate the iteration
typedef int GIT_CALLBACK(git_reference_foreach_cb)(git_reference *reference, void *payload);
* Callback used to iterate over reference names
* @see git_reference_foreach_name
* @param name The reference name
* @param payload Payload passed to git_reference_foreach_name
* @return non-zero to terminate the iteration
typedef int GIT_CALLBACK(git_reference_foreach_name_cb)(const char *name, void *payload);
* Perform a callback on each reference in the repository.
* The `callback` function will be called for each reference in the
* repository, receiving the reference object and the `payload` value
* passed to this method. Returning a non-zero value from the callback
* will terminate the iteration.
* Note that the callback function is responsible to call `git_reference_free`
* on each reference passed to it.
* @param repo Repository where to find the refs
* @param callback Function which will be called for every listed ref
* @param payload Additional data to pass to the callback
* @return 0 on success, non-zero callback return value, or error code
GIT_EXTERN(int) git_reference_foreach(
git_reference_foreach_cb callback,
* Perform a callback on the fully-qualified name of each reference.
* The `callback` function will be called for each reference in the
* repository, receiving 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 callback Function which will be called for every listed ref name
* @param payload Additional data to pass to the callback
* @return 0 on success, non-zero callback return value, or error code
GIT_EXTERN(int) git_reference_foreach_name(
git_reference_foreach_name_cb callback,
* Create a copy of an existing reference.
* Call `git_reference_free` to free the data.
* @param dest pointer where to store the copy
* @param source object to copy
* @return 0 or an error code
GIT_EXTERN(int) git_reference_dup(git_reference **dest, git_reference *source);
* Free the given reference.
* @param ref git_reference
It is recommended that you Edit text format, this type of Fix handles quite a lot in one request
