References
- class pygit2.Repository(path: str | None = None, flags: RepositoryOpenFlag = RepositoryOpenFlag.DEFAULT)
- references
Returns an instance of the References class (see below).
- lookup_reference(name: str) Reference
Lookup a reference by its name in a repository.
- lookup_reference_dwim(name: str) Reference
Lookup a reference by doing-what-i-mean’ing its short name.
- raw_listall_references() list[bytes]
Return a list with all the references in the repository.
- resolve_refish(refish)
Convert a reference-like short name “ref-ish” to a valid (commit, reference) pair.
If ref-ish points to a commit, the reference element of the result will be None.
Examples:
repo.resolve_refish('mybranch') repo.resolve_refish('sometag') repo.resolve_refish('origin/master') repo.resolve_refish('bbb78a9')
- class pygit2.repository.References(repository: BaseRepository)
- __contains__(name: str)
- __getitem__(name: str)
- __iter__()
- compress()
- create(name, target, force=False)
- delete(name: str)
- get(key: str)
- iterator(references_return_type: ReferenceFilter = ReferenceFilter.ALL)
Creates a new iterator and fetches references for a given repository.
Can also filter and pass all refs or only branches or only tags.
Parameters:
- references_return_type: ReferenceFilter
Optional specifier to filter references. By default, all references are returned.
The following values are accepted: - ReferenceFilter.ALL, fetches all refs, this is the default - ReferenceFilter.BRANCHES, fetches only branches - ReferenceFilter.TAGS, fetches only tags
TODO: Add support for filtering by reference types notes and remotes.
- property objects
Example:
>>> all_refs = list(repo.references)
>>> master_ref = repo.references["refs/heads/master"]
>>> commit = master_ref.peel() # or repo[master_ref.target]
# Create a reference
>>> ref = repo.references.create('refs/tags/version1', LAST_COMMIT)
# Delete a reference
>>> repo.references.delete('refs/tags/version1')
# Pack loose references
>>> repo.references.compress()
Functions
- pygit2.reference_is_valid_name(refname: str) bool
Check if the passed string is a valid reference name.
Check if the passed string is a valid reference name.
Example:
>>> from pygit2 import reference_is_valid_name >>> reference_is_valid_name("refs/heads/master") True >>> reference_is_valid_name("HEAD") True >>> reference_is_valid_name("refs/heads/..") False
The Reference type
- class pygit2.Reference
Reference(name: str, target: str): create a symbolic reference
Reference(name: str, oid: Oid, peel: Oid): create a direct reference
‘peel’ is the first non-tag object’s OID, or None.
The purpose of this constructor is for use in custom refdb backends. References created with this function are unlikely to work as expected in other contexts.
- log() RefLogIter
Retrieves the current reference log.
- __eq__(value, /)
Return self==value.
- __ne__(value, /)
Return self!=value.
- delete()
Delete this reference. It will no longer be valid!
- name
The full name of the reference.
- peel(type=None) Object
Retrieve an object of the given type by recursive peeling.
If no type is provided, the first non-tag object will be returned.
- raw_name
The full name of the reference (Bytes).
- raw_shorthand
The shorthand “human-readable” name of the reference (Bytes).
- raw_target
The raw reference target: If direct the value will be an Oid object, if it is symbolic it will be bytes with the full name of the target reference.
- rename(new_name: str)
Rename the reference.
- set_target(target[, message: str])
Set the target of this reference. Creates a new entry in the reflog.
Parameters:
- target
The new target for this reference
- message
Message to use for the reflog.
- shorthand
The shorthand “human-readable” name of the reference.
- target
The reference target: If direct the value will be an Oid object, if it is symbolic it will be an string with the full name of the target reference.
- type
An enums.ReferenceType constant (either OID or SYMBOLIC).
The HEAD
Example. These two lines are equivalent:
>>> head = repo.references['HEAD'].resolve()
>>> head = repo.head
- Repository.head
Current head reference of the repository.
- Repository.head_is_detached
A repository’s HEAD is detached when it points directly to a commit instead of a branch.
- Repository.head_is_unborn
An unborn branch is one named from HEAD but which doesn’t exist in the refs namespace, because it doesn’t have any commit to point to.
The reference log
Example:
>>> head = repo.references.get('refs/heads/master') # Returns None if not found
>>> # Almost equivalent to
>>> head = repo.references['refs/heads/master'] # Raises KeyError if not found
>>> for entry in head.log():
... print(entry.message)
Notes
- Repository.notes()
- Repository.create_note(message: str, author: Signature, committer: Signature, annotated_id: str, ref: str = 'refs/notes/commits', force: bool = False) Oid
Create a new note for an object, return its SHA-ID.If no ref is given ‘refs/notes/commits’ will be used.
- Repository.lookup_note(annotated_id: str, ref: str = 'refs/notes/commits') Note
Lookup a note for an annotated object in a repository.
The Note type
- Note.annotated_id
id of the annotated object.
- Note.id
id of the note object.
- Note.message
Gets message of the note