33 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:

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.

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:

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).

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.

Call git_reference_free to free the data.

Apply the git precendence rules to the given shorthand to determine which reference the user is referring to.

Make sure that successive updates to the reference will append to its log.

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.

This function acts like git_reference_foreach() with an additional pattern match being applied to the reference name before issuing the callback function. See that function for more information.

The pattern is matched using fnmatch or "glob" style where a ’*’ matches any sequence of letters, a ’?’ matches any letter, and square brackets can be used to define character ranges (such as "[0-9]" for digits).

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.

Valid reference names must follow one of two patterns:

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.

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().

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.

See git_reference_symbolic_create() for rules about valid names.

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.

This function is provided for convenience in case only the names are interesting as it avoids the allocation of the git_reference object which git_reference_next() needs.

This will 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.

See git_reference_symbolic_create() for rules about valid names.

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.

This method removes the named reference from the repository without looking at its old value.

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.

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.

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.

The new reference will be written to disk, overwriting the given reference.

This will transform the reference name into a name "human-readable" version. If no shortname is appropriate, it will return the full name.

The memory is owned by the reference and must not be freed.

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:

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.

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:

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).

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.

Only available if the reference is symbolic.

Only available if the reference is direct (i.e. an object id reference, not a symbolic one).

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).

This peeled OID only applies to direct references that point to a hard Tag object: it is the result of peeling such Tag.

Either direct (GIT_REF_OID) or symbolic (GIT_REF_SYMBOLIC)