2.36 Reference

7.7

top ← prev up next →

2.36 Reference

(require libgit2/include/refs)

package: libgit2

procedure
(git_reference__alloc name oid peel) → reference?
  name : string?
  oid : oid?
  peel : (or/c oid? #f)

Create a new direct reference from an OID.

procedure
(git_reference__alloc_symbolic name target) → reference?
name : string?
target : string?

Create a new symbolic reference.

procedure
(git_reference_cmp ref1 ref2) → 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

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:

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_delete ref) → 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_dup source) → reference?
source : reference?

Create a copy of an existing reference.

Call git_reference_free to free the data.

procedure
(git_reference_dwim repo shorthand) → 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_log repo refname) → 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_free ref) → void?
ref : reference?

Free the given reference.

procedure
(git_reference_has_log repo refname) → boolean?
repo : repository?
refname : string?

Check if a reflog exists for the specified reference.

procedure
(git_reference_is_branch ref) → boolean?
ref : reference?

Check if a reference is a local branch.

procedure
(git_reference_is_note ref) → boolean?
ref : reference?

Check if a reference is a note

procedure
(git_reference_is_remote ref) → boolean?
ref : reference?

Check if a reference is a remote tracking branch

procedure
(git_reference_is_tag ref) → boolean?
ref : reference?

Check if a reference is a tag

procedure
(git_reference_is_valid_name refname) → boolean?
refname : string?

Ensure the reference name is well-formed.

Valid reference names must follow one of two patterns:

procedure
(git_reference_iterator_free iter) → void?
iter : reference_iterator?

Free the iterator and its associated resources

procedure
(git_reference_iterator_glob_new repo glob)
→ reference_iterator?
repo : repository?
glob : string?

Create an iterator for the repo’s references that match the specified glob

procedure
(git_reference_iterator_new repo) → reference_iterator?
repo : repository?

Create an iterator for the repo’s references

procedure
(git_reference_list array repo) → 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_lookup repo name) → 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_name ref) → 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_id out repo name) → 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_next iter) → reference?
iter : reference_iterator?

Get the next reference

procedure
(git_reference_next_name iter) → 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_owner ref) → repository?
ref : reference?

Get the repository where a reference resides.

procedure
(git_reference_peel ref type) → 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_remove repo name) → 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_resolve ref) → 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_shorthand ref) → 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:

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.

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:

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_target ref) → 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_target ref) → 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_peel ref) → 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_type ref) → git_ref_t
ref : reference?

Get the type of a reference.

Either direct (GIT_REF_OID) or symbolic (GIT_REF_SYMBOLIC)

top ← prev up next →

1	Background
2	Functions
	Bibliography
	Index

2.1	Annotated Commit
2.2	Blame
2.3	Blob
2.4	Branch
2.5	Buffer
2.6	Checkout
2.7	Cherrypick
2.8	Clone
2.9	Commit
2.10	Config
2.11	Credentials
2.12	Describe
2.13	Diff
2.14	Fetch
2.15	Filter
2.16	Errors
2.17	Graph
2.18	Ignore
2.19	Index
2.20	Indexer
2.21	Global
2.22	Merge
2.23	Message
2.24	Note
2.25	Object
2.26	Object Database
2.27	Oid
2.28	Oid Array
2.29	Packbuilder
2.30	Patch
2.31	Pathspec
2.32	Proxy
2.33	Push
2.34	Rebase
2.35	Refdb
2.36	Reference
2.37	Reflog
2.38	Refspec
2.39	Remote
2.40	Repository
2.41	Reset
2.42	Revert
2.43	Revparse
2.44	Revwalk
2.45	Signature
2.46	Stash
2.47	Status
2.48	Strarray
2.49	Submodule
2.50	Tag
2.51	Tree
2.52	Treebuilder