dulwich.refs.DiskRefsContainer

class documentation

class DiskRefsContainer(RefsContainer):

Constructor: DiskRefsContainer(path, worktree_path, logger)

Refs container that reads refs from disk.

Method	`__init__`	Initialize DiskRefsContainer.
Method	`__repr__`	Return string representation of DiskRefsContainer.
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`	Return all reference keys.
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	`pack_refs`	Pack loose refs into packed-refs file.
Method	`read_loose_ref`	Read a reference file and return its contents.
Method	`refpath`	Return the disk path of a ref.
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`	Return subkeys under a given base reference path.
Instance Variable	`path`	Undocumented
Instance Variable	`worktree_path`	Undocumented
Method	`_iter_dir`	Undocumented
Method	`_iter_loose_refs`	Undocumented
Method	`_remove_packed_ref`	Undocumented
Instance Variable	`_packed_refs`	Undocumented
Instance Variable	`_peeled_refs`	Undocumented

Inherited from RefsContainer:

Method	`__contains__`	Check if a reference exists.
Method	`__delitem__`	Remove a refname.
Method	`__getitem__`	Get the SHA1 for a reference name.
Method	`__iter__`	Iterate over all reference keys.
Method	`__setitem__`	Set a reference name to point to the given SHA1.
Method	`as_dict`	Return the contents of this container as a dictionary.
Method	`follow`	Follow a reference name.
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	`read_ref`	Read a reference without following any references.
Method	`_check_refname`	Ensure a refname is valid and lives in refs or is HEAD.
Method	`_log`	Undocumented
Instance Variable	`_logger`	Undocumented

overrides dulwich.refs.RefsContainer.__init__

Initialize DiskRefsContainer.

def __repr__(self) -> str: ¶

Return string representation of DiskRefsContainer.

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

overrides dulwich.refs.RefsContainer.add_if_new

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

This method follows symrefs, and only ensures that the last ref in the chain does not exist.

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

Parameters
name:`Ref`	The refname to set.
ref:`ObjectID`	The new sha the refname will refer to.
committer:`bytes \| None`	Optional committer name
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]): ¶

overrides dulwich.refs.RefsContainer.add_packed_refs

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]: ¶

overrides dulwich.refs.RefsContainer.allkeys

Return all reference keys.

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

overrides dulwich.refs.RefsContainer.get_packed_refs

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

overrides dulwich.refs.RefsContainer.get_peeled

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 pack_refs(self, all: bool = False): ¶

overrides dulwich.refs.RefsContainer.pack_refs

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

overrides dulwich.refs.RefsContainer.read_loose_ref

Read a reference file and return its contents.

If the reference file a symbolic reference, only read the first line of the file. Otherwise, read the hash (40 bytes for SHA1, 64 bytes for SHA256).

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

Parameters
name:`Ref`	the refname to read, relative to refpath

Returns
`bytes \| None`	Undocumented

Raises
`IOError`	if any other error occurs

def refpath(self, name: bytes) -> bytes: ¶

Return the disk path of a ref.

overrides dulwich.refs.RefsContainer.remove_if_equals

Remove a refname only if it currently equals old_ref.

This method does not follow symbolic references. 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
timestamp:`int \| None`	Optional timestamp
timezone:`int \| None`	Optional timezone
message:`bytes \| None`	Optional message

Returns
`bool`	Undocumented

overrides dulwich.refs.RefsContainer.set_if_equals

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

This method follows all symbolic references, 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
timestamp:`int \| None`	Optional timestamp
timezone:`int \| None`	Optional timezone
message:`bytes \| None`	Set 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): ¶

overrides dulwich.refs.RefsContainer.set_symbolic_ref

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
timestamp:`int \| None`	Optional timestamp
timezone:`int \| None`	Optional timezone
message:`bytes \| None`	Optional message to describe the change

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

overrides dulwich.refs.RefsContainer.subkeys

Return subkeys under a given base reference path.

path = ¶

Undocumented

worktree_path = ¶

Undocumented

def _iter_dir(self, path: bytes, base: bytes, dir_filter: Callable[[bytes], bool] | None = None) -> Iterator[Ref]: ¶

Undocumented

def _iter_loose_refs(self, base: bytes = b'refs/') -> Iterator[Ref]: ¶

Undocumented

def _remove_packed_ref(self, name: Ref): ¶

Undocumented

_packed_refs: dict[Ref, ObjectID] | None = ¶

Undocumented

_peeled_refs: dict[Ref, ObjectID] | None = ¶

Undocumented