On this page:
8.18
top
up

33ReferenceπŸ”— i

procedure

( git_reference__allocnameoidpeel)reference?

name:string?
oid:oid?
peel:(or/c oid?#f)
Create a new direct reference from an OID.

procedure

( git_reference__alloc_symbolicnametarget)reference?

name:string?
target:string?
Create a new symbolic reference.

procedure

( git_reference_cmpref1ref2)integer?

ref1:reference?
ref2:reference?
Compare two references.

procedure

( git_reference_create repo
name
id
force
log_message)reference?
repo:repository?
name:string?
id:oid?
force:boolean?
log_message:string?
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:

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.

procedure

( git_reference_create_matching repo
name
id
force
current_id
log_message)reference?
repo:repository?
name:string?
id:oid?
force:boolean?
current_id:oid?
log_message:string?
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:

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

procedure

( git_reference_deleteref)integer?

ref:reference?
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.

procedure

( git_reference_dupsource)reference?

source:reference?
Create a copy of an existing reference.

Call git_reference_free to free the data.

procedure

( git_reference_dwimreposhorthand)reference?

repo:repository?
shorthand:string?
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.

procedure

( git_reference_ensure_logreporefname)integer?

repo:repository?
refname:string?
Ensure there is a reflog for a particular reference.

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

procedure

( git_reference_foreach repo
callback
payload)integer?
repo:repository?
callback:git_reference_foreach_cb
payload:bytes?
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.

procedure

( git_reference_foreach_glob repo
glob
callback
payload)integer?
repo:repository?
glob:string?
callback:git_reference_foreach_name_cb
payload:bytes?
Perform a callback on each reference in the repository whose name matches the given pattern.

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

procedure

( git_reference_foreach_name repo
callback
payload)integer?
repo:repository?
callback:git_reference_foreach_name_cb
payload:bytes?
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.

procedure

( git_reference_freeref)void?

ref:reference?
Free the given reference.

procedure

( git_reference_has_logreporefname)boolean?

repo:repository?
refname:string?
Check if a reflog exists for the specified reference.

procedure

( git_reference_is_branchref)boolean?

ref:reference?
Check if a reference is a local branch.

procedure

( git_reference_is_noteref)boolean?

ref:reference?
Check if a reference is a note

procedure

( git_reference_is_remoteref)boolean?

ref:reference?
Check if a reference is a remote tracking branch

procedure

( git_reference_is_tagref)boolean?

ref:reference?
Check if a reference is a tag

procedure

( git_reference_is_valid_namerefname)boolean?

refname:string?
Ensure the reference name is well-formed.

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.

procedure

( git_reference_iterator_freeiter)void?

iter:reference_iterator?
Free the iterator and its associated resources

procedure

( git_reference_iterator_glob_newrepoglob)

reference_iterator?
repo:repository?
glob:string?
Create an iterator for the repo’s references that match the specified glob

procedure

( git_reference_iterator_newrepo)reference_iterator?

repo:repository?
Create an iterator for the repo’s references

procedure

( git_reference_listarrayrepo)integer?

array:strarray?
repo:repository?
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().

procedure

( git_reference_lookupreponame)reference?

repo:repository?
name:string?
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.

procedure

( git_reference_nameref)integer?

ref:reference?
Get the full name of a reference.

See git_reference_symbolic_create() for rules about valid names.

procedure

( git_reference_name_to_idoutreponame)integer?

out:oid?
repo:repository?
name:string?
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.

procedure

( git_reference_nextiter)reference?

iter:reference_iterator?
Get the next reference

procedure

( git_reference_next_nameiter)string?

iter:reference_iterator?
Get the next reference’s name

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.

procedure

( git_reference_normalize_name buffer_out
buffer_size
name
flags)integer?
buffer_out:string?
buffer_size:integer?
name:string?
flags:integer?
Normalize reference name and check validity.

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.

procedure

( git_reference_ownerref)repository?

ref:reference?
Get the repository where a reference resides.

procedure

( git_reference_peelreftype)object?

ref:reference?
type:git_otype
Recursively peel reference until object of the specified type is found.

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.

procedure

( git_reference_removereponame)integer?

repo:repository?
name:string?
Delete an existing reference by name

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

procedure

( git_reference_rename ref
new_name
force
log_message)reference?
ref:reference?
new_name:string?
force:boolean?
log_message:string?
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.

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.

procedure

( git_reference_resolveref)reference?

ref:reference?
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.

procedure

( git_reference_set_target ref
id
log_message)reference?
ref:reference?
id:oid?
log_message:string?
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 this will fail.

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

procedure

( git_reference_shorthandref)string?

ref:reference?
Get the reference’s short name

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.

procedure

( git_reference_symbolic_create repo
name
target
force
log_message)reference?
repo:repository?
name:string?
target:string?
force:boolean?
log_message:string?
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:

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.

procedure

( git_reference_symbolic_create_matching repo
name
target
force
current_value
log_message)
reference?
repo:repository?
name:string?
target:string?
force:boolean?
current_value:string?
log_message:string?
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:

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

procedure

( git_reference_symbolic_set_target ref
target
log_message)reference?
ref:reference?
target:string?
log_message:string?
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.

procedure

( git_reference_symbolic_targetref)string?

ref:reference?
Get full name to the reference pointed to by a symbolic reference.

Only available if the reference is symbolic.

procedure

( git_reference_targetref)oid?

ref:reference?
Get the OID pointed to by a direct reference.

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

procedure

( git_reference_target_peelref)oid?

ref:reference?
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.

procedure

( git_reference_typeref)git_ref_t

ref:reference?
Get the type of a reference.

Either direct (GIT_REF_OID) or symbolic (GIT_REF_SYMBOLIC)

top
up

AltStyle γ«γ‚ˆγ£γ¦ε€‰ζ›γ•γ‚ŒγŸγƒšγƒΌγ‚Έ (->γ‚ͺγƒͺγ‚ΈγƒŠγƒ«) /