dulwich.refs.RefsContainer

class documentation

class RefsContainer:

Known subclasses: dulwich.refs.DictRefsContainer, dulwich.refs.DiskRefsContainer, dulwich.refs.NamespacedRefsContainer, dulwich.reftable.ReftableRefsContainer

Constructor: RefsContainer(logger)

View In Hierarchy

A container for refs.

Method	`__contains__`	Check if a reference exists.
Method	`__delitem__`	Remove a refname.
Method	`__getitem__`	Get the SHA1 for a reference name.
Method	`__init__`	Initialize RefsContainer with optional logger function.
Method	`__iter__`	Iterate over all reference keys.
Method	`__setitem__`	Set a reference name to point to the given SHA1.
Method	`add_if_new`	Add a new reference only if it does not already exist.
Method	`add_packed_refs`	Add the given refs as packed refs.
Method	`allkeys`	All refs present in this container.
Method	`as_dict`	Return the contents of this container as a dictionary.
Method	`follow`	Follow a reference name.
Method	`get_packed_refs`	Get contents of the packed-refs file.
Method	`get_peeled`	Return the cached peeled value of a ref, if available.
Method	`get_symrefs`	Get a dict with all symrefs in this container.
Method	`import_refs`	Import refs from another repository.
Method	`keys`	Refs present in this container.
Method	`pack_refs`	Pack loose refs into packed-refs file.
Method	`read_loose_ref`	Read a loose reference and return its contents.
Method	`read_ref`	Read a reference without following any references.
Method	`remove_if_equals`	Remove a refname only if it currently equals old_ref.
Method	`set_if_equals`	Set a refname to new_ref only if it currently equals old_ref.
Method	`set_symbolic_ref`	Make a ref point at another ref.
Method	`subkeys`	Refs present in this container under a base.
Method	`_check_refname`	Ensure a refname is valid and lives in refs or is HEAD.
Method	`_log`	Undocumented
Instance Variable	`_logger`	Undocumented

def __contains__(self, refname: Ref) -> bool: ¶

Check if a reference exists.

def __delitem__(self, name: Ref): ¶

Remove a refname.

This method does not follow symbolic references, even if applicable for the subclass.

Note: This method unconditionally deletes the contents of a reference.: To delete atomically only if the reference has not changed, use remove_if_equals().

Parameters
name:`Ref`	The refname to delete.

def __getitem__(self, name: Ref) -> ObjectID: ¶

overridden in dulwich.reftable.ReftableRefsContainer

Get the SHA1 for a reference name.

This method follows all symbolic references.

def __init__(self, logger: Callable[[bytes, bytes, bytes, (bytes | None), (int | None), (int | None), bytes], None] | None = None): ¶

overridden in dulwich.refs.DictRefsContainer, dulwich.refs.DiskRefsContainer, dulwich.refs.NamespacedRefsContainer, dulwich.reftable.ReftableRefsContainer

Initialize RefsContainer with optional logger function.

def __iter__(self) -> Iterator[Ref]: ¶

Iterate over all reference keys.

def __setitem__(self, name: Ref, ref: ObjectID): ¶

Set a reference name to point to the given SHA1.

This method follows all symbolic references if applicable for the subclass.

Note: This method unconditionally overwrites the contents of a: reference. To update atomically only if the reference has not changed, use set_if_equals().

Parameters
name:`Ref`	The refname to set.
ref:`ObjectID`	The new sha the refname will refer to.

def add_if_new(self, name: Ref, ref: ObjectID, committer: bytes | None = None, timestamp: int | None = None, timezone: int | None = None, message: bytes | None = None) -> bool: ¶

overridden in dulwich.refs.DictRefsContainer, dulwich.refs.DiskRefsContainer, dulwich.refs.NamespacedRefsContainer, dulwich.reftable.ReftableRefsContainer

Add a new reference only if it does not already exist.

Parameters
name:`Ref`	Ref name
ref:`ObjectID`	Ref value
committer:`bytes \| None`	Optional committer name/email
timestamp:`int \| None`	Optional timestamp
timezone:`int \| None`	Optional timezone
message:`bytes \| None`	Optional message for reflog

Returns
`bool`	Undocumented

def add_packed_refs(self, new_refs: Mapping[Ref, ObjectID | None]): ¶

overridden in dulwich.refs.DiskRefsContainer, dulwich.refs.NamespacedRefsContainer, dulwich.reftable.ReftableRefsContainer

Add the given refs as packed refs.

Parameters
new_refs:`Mapping[Ref, ObjectID \| None]`	A mapping of ref names to targets; if a target is None that means remove the ref

def allkeys(self) -> set[Ref]: ¶

overridden in dulwich.refs.DictRefsContainer, dulwich.refs.DiskRefsContainer, dulwich.refs.NamespacedRefsContainer, dulwich.reftable.ReftableRefsContainer

All refs present in this container.

def as_dict(self, base: Ref | None = None) -> dict[Ref, ObjectID]: ¶

Return the contents of this container as a dictionary.

def follow(self, name: Ref) -> tuple[list[Ref], ObjectID | None]: ¶

overridden in dulwich.reftable.ReftableRefsContainer

Follow a reference name.

Returns: a tuple of (refnames, sha), wheres refnames are the names of: references in the chain

def get_packed_refs(self) -> dict[Ref, ObjectID]: ¶

overridden in dulwich.refs.DictRefsContainer, dulwich.refs.DiskRefsContainer, dulwich.refs.NamespacedRefsContainer, dulwich.reftable.ReftableRefsContainer

Get contents of the packed-refs file.

Returns: Dictionary mapping ref names to SHA1s

Note: Will return an empty dictionary when no packed-refs file is: present.

def get_peeled(self, name: Ref) -> ObjectID | None: ¶

overridden in dulwich.refs.DictRefsContainer, dulwich.refs.DiskRefsContainer, dulwich.refs.NamespacedRefsContainer, dulwich.reftable.ReftableRefsContainer

Return the cached peeled value of a ref, if available.

Returns: The peeled value of the ref. If the ref is known not point to: a tag, this will be the SHA the ref refers to. If the ref may point to a tag, but no cached information is available, None is returned.

Parameters
name:`Ref`	Name of the ref to peel

Returns
`ObjectID \| None`	Undocumented

def get_symrefs(self) -> dict[Ref, Ref]: ¶

Get a dict with all symrefs in this container.

Returns: Dictionary mapping source ref to target ref

Import refs from another repository.

Parameters
base:`Ref`	Base ref to import into (e.g., b'refs/remotes/origin')
other:`Mapping[Ref, ObjectID \| None]`	Dictionary of refs to import
committer:`bytes \| None`	Optional committer for reflog
timestamp:`bytes \| None`	Optional timestamp for reflog
timezone:`bytes \| None`	Optional timezone for reflog
message:`bytes \| None`	Optional message for reflog
prune:`bool`	If True, remove refs not in other

def keys(self, base: Ref | None = None) -> set[Ref]: ¶

Refs present in this container.

Returns: An unsorted set of valid refs in this container, including: packed refs.

Parameters
base:`Ref \| None`	An optional base to return refs under.

Returns
`set[Ref]`	Undocumented

def pack_refs(self, all: bool = False): ¶

overridden in dulwich.refs.DiskRefsContainer, dulwich.refs.NamespacedRefsContainer

Pack loose refs into packed-refs file.

Parameters
all:`bool`	If True, pack all refs. If False, only pack tags.

def read_loose_ref(self, name: Ref) -> bytes | None: ¶

overridden in dulwich.refs.DictRefsContainer, dulwich.refs.DiskRefsContainer, dulwich.refs.NamespacedRefsContainer, dulwich.reftable.ReftableRefsContainer

Read a loose reference and return its contents.

Returns: The contents of the ref file, or None if it does: not exist.

Parameters
name:`Ref`	the refname to read

Returns
`bytes \| None`	Undocumented

def read_ref(self, refname: Ref) -> bytes | None: ¶

Read a reference without following any references.

Returns: The contents of the ref file, or None if it does: not exist.

Parameters
refname:`Ref`	The name of the reference

Returns
`bytes \| None`	Undocumented

overridden in dulwich.refs.DictRefsContainer, dulwich.refs.DiskRefsContainer, dulwich.refs.NamespacedRefsContainer, dulwich.reftable.ReftableRefsContainer

Remove a refname only if it currently equals old_ref.

This method does not follow symbolic references, even if applicable for the subclass. It can be used to perform an atomic compare-and-delete operation.

Returns: True if the delete was successful, False otherwise.

Parameters
name:`Ref`	The refname to delete.
old_ref:`ObjectID \| None`	The old sha the refname must refer to, or None to delete unconditionally.
committer:`bytes \| None`	Optional committer name/email
timestamp:`int \| None`	Optional timestamp
timezone:`int \| None`	Optional timezone
message:`bytes \| None`	Message for reflog

Returns
`bool`	Undocumented

overridden in dulwich.refs.DictRefsContainer, dulwich.refs.DiskRefsContainer, dulwich.refs.NamespacedRefsContainer, dulwich.reftable.ReftableRefsContainer

Set a refname to new_ref only if it currently equals old_ref.

This method follows all symbolic references if applicable for the subclass, and can be used to perform an atomic compare-and-swap operation.

Returns: True if the set was successful, False otherwise.

Parameters
name:`Ref`	The refname to set.
old_ref:`ObjectID \| None`	The old sha the refname must refer to, or None to set unconditionally.
new_ref:`ObjectID`	The new sha the refname will refer to.
committer:`bytes \| None`	Optional committer name/email
timestamp:`int \| None`	Optional timestamp
timezone:`int \| None`	Optional timezone
message:`bytes \| None`	Message for reflog

Returns
`bool`	Undocumented

def set_symbolic_ref(self, name: Ref, other: Ref, committer: bytes | None = None, timestamp: int | None = None, timezone: int | None = None, message: bytes | None = None): ¶

overridden in dulwich.refs.DictRefsContainer, dulwich.refs.DiskRefsContainer, dulwich.refs.NamespacedRefsContainer, dulwich.reftable.ReftableRefsContainer

Make a ref point at another ref.

Parameters
name:`Ref`	Name of the ref to set
other:`Ref`	Name of the ref to point at
committer:`bytes \| None`	Optional committer name/email
timestamp:`int \| None`	Optional timestamp
timezone:`int \| None`	Optional timezone
message:`bytes \| None`	Optional message

def subkeys(self, base: Ref) -> set[Ref]: ¶

overridden in dulwich.refs.DiskRefsContainer

Refs present in this container under a base.

Returns: A set of valid refs in this container under the base; the base: prefix is stripped from the ref names returned.

Parameters
base:`Ref`	The base to return refs under.

Returns
`set[Ref]`	Undocumented

def _check_refname(self, name: Ref): ¶

Ensure a refname is valid and lives in refs or is HEAD.

HEAD is not a valid refname according to git-check-ref-format, but this class needs to be able to touch HEAD. Also, check_ref_format expects refnames without the leading 'refs/', but this class requires that so it cannot touch anything outside the refs dir (or HEAD).

Parameters
name:`Ref`	The name of the reference.

Raises
`KeyError`	if a refname is not HEAD or is otherwise not valid.

Undocumented

_logger = ¶

Undocumented