dulwich.refs

module documentation

Ref handling.

Class	`DictRefsContainer`	RefsContainer backed by a simple dict.
Class	`DiskRefsContainer`	Refs container that reads refs from disk.
Class	`locked_ref`	Lock a ref while making modifications.
Class	`NamespacedRefsContainer`	Wrapper that adds namespace prefix to all ref operations.
Class	`RefsContainer`	A container for refs.
Exception	`SymrefLoop`	There is a loop between one or more symrefs.
Function	`check_ref_format`	Check if a refname is correctly formatted.
Function	`extract_branch_name`	Extract branch name from a full branch ref.
Function	`extract_tag_name`	Extract tag name from a full tag ref.
Function	`filter_ref_prefix`	Filter refs to only include those with a given prefix.
Function	`is_local_branch`	Check if a ref name is a local branch.
Function	`is_per_worktree_ref`	Returns whether a reference is stored per worktree or not.
Function	`local_branch_name`	Build a full branch ref from a short name.
Function	`local_replace_name`	Build a full replace ref from a short name.
Function	`local_tag_name`	Build a full tag ref from a short name.
Function	`parse_remote_ref`	Parse a remote ref into remote name and branch name.
Function	`parse_symref_value`	Parse a symref value.
Function	`read_info_refs`	Read info/refs file.
Function	`read_packed_refs`	Read a packed refs file.
Function	`read_packed_refs_with_peeled`	Read a packed refs file including peeled refs.
Function	`set_ref_from_raw`	Set a reference from a raw ref value.
Function	`shorten_ref_name`	Convert a full ref name to its short form.
Function	`write_packed_refs`	Write a packed refs file.
Constant	`BAD_REF_CHARS`	Undocumented
Constant	`HEADREF`	Undocumented
Constant	`LOCAL_BRANCH_PREFIX`	Undocumented
Constant	`LOCAL_NOTES_PREFIX`	Undocumented
Constant	`LOCAL_REMOTE_PREFIX`	Undocumented
Constant	`LOCAL_REPLACE_PREFIX`	Undocumented
Constant	`LOCAL_TAG_PREFIX`	Undocumented
Constant	`SYMREF`	Undocumented
Type Variable	`T`	Undocumented
Variable	`Ref`	Undocumented
Function	`_import_remote_refs`	Undocumented
Function	`_set_default_branch`	Set the default branch.
Function	`_set_head`	Undocumented
Function	`_set_origin_head`	Undocumented
Function	`_split_ref_line`	Split a single ref line into a tuple of SHA1 and name.

def check_ref_format(refname: Ref) -> bool: ¶

Check if a refname is correctly formatted.

Implements all the same rules as git-check-ref-format[1].

[1] http://www.kernel.org/pub/software/scm/git/docs/git-check-ref-format.html

Returns: True if refname is valid, False otherwise

Parameters
refname:`Ref`	The refname to check

Returns
`bool`	Undocumented

def extract_branch_name(ref: bytes) -> bytes: ¶

Extract branch name from a full branch ref.

Examples

>>> extract_branch_name(b"refs/heads/master")
b'master'
>>> extract_branch_name(b"refs/heads/feature/foo")
b'feature/foo'

Parameters
ref:`bytes`	Full branch ref (e.g., b"refs/heads/master")

Returns
`bytes`	Short branch name (e.g., b"master")

Raises
`ValueError`	If ref is not a local branch

def extract_tag_name(ref: bytes) -> bytes: ¶

Extract tag name from a full tag ref.

Examples

>>> extract_tag_name(b"refs/tags/v1.0")
b'v1.0'

Parameters
ref:`bytes`	Full tag ref (e.g., b"refs/tags/v1.0")

Returns
`bytes`	Short tag name (e.g., b"v1.0")

Raises
`ValueError`	If ref is not a local tag

def filter_ref_prefix(refs: T, prefixes: Iterable[bytes]) -> T: ¶

Filter refs to only include those with a given prefix.

Parameters
refs:`T`	A dictionary of refs.
prefixes:`Iterable[bytes]`	The prefixes to filter by.

Returns
`T`	Undocumented

def is_local_branch(x: bytes) -> bool: ¶

Check if a ref name is a local branch.

def is_per_worktree_ref(ref: bytes) -> bool: ¶

Returns whether a reference is stored per worktree or not.

Per-worktree references are: - all pseudorefs, e.g. HEAD - all references stored inside "refs/bisect/", "refs/worktree/" and "refs/rewritten/"

All refs starting with "refs/" are shared, except for the ones listed above.

See https://git-scm.com/docs/git-worktree#_refs.

def local_branch_name(name: bytes) -> Ref: ¶

Build a full branch ref from a short name.

Examples

>>> local_branch_name(b"master")
b'refs/heads/master'
>>> local_branch_name(b"refs/heads/master")
b'refs/heads/master'

Parameters
name:`bytes`	Short branch name (e.g., b"master") or full ref

Returns
`Ref`	Full branch ref name (e.g., b"refs/heads/master")

def local_replace_name(name: bytes) -> Ref: ¶

Build a full replace ref from a short name.

Examples

>>> local_replace_name(b"abc123")
b'refs/replace/abc123'
>>> local_replace_name(b"refs/replace/abc123")
b'refs/replace/abc123'

Parameters
name:`bytes`	Short replace name (object SHA) or full ref

Returns
`Ref`	Full replace ref name (e.g., b"refs/replace/<sha>")

def local_tag_name(name: bytes) -> Ref: ¶

Build a full tag ref from a short name.

Examples

>>> local_tag_name(b"v1.0")
b'refs/tags/v1.0'
>>> local_tag_name(b"refs/tags/v1.0")
b'refs/tags/v1.0'

Parameters
name:`bytes`	Short tag name (e.g., b"v1.0") or full ref

Returns
`Ref`	Full tag ref name (e.g., b"refs/tags/v1.0")

def parse_remote_ref(ref: bytes) -> tuple[bytes, bytes]: ¶

Parse a remote ref into remote name and branch name.

Parameters
ref:`bytes`	Remote ref like b"refs/remotes/origin/main"

Returns
`tuple[bytes, bytes]`	Tuple of (remote_name, branch_name)

Raises
`ValueError`	If ref is not a valid remote ref

def parse_symref_value(contents: bytes) -> bytes: ¶

Parse a symref value.

Returns: Destination

Parameters
contents:`bytes`	Contents to parse

Returns
`bytes`	Undocumented

def read_info_refs(f: BinaryIO) -> dict[Ref, ObjectID]: ¶

Read info/refs file.

Parameters
f:`BinaryIO`	File-like object to read from

Returns
`dict[Ref, ObjectID]`	Dictionary mapping ref names to SHA1s

def read_packed_refs(f: IO[bytes]) -> Iterator[tuple[ObjectID, Ref]]: ¶

Read a packed refs file.

Returns: Iterator over tuples with SHA1s and ref names.

Parameters
f:`IO[bytes]`	file-like object to read from

Returns
`Iterator[tuple[ObjectID, Ref]]`	Undocumented

def read_packed_refs_with_peeled(f: IO[bytes]) -> Iterator[tuple[ObjectID, Ref, ObjectID | None]]: ¶

Read a packed refs file including peeled refs.

Assumes the "# pack-refs with: peeled" line was already read. Yields tuples with ref names, SHA1s, and peeled SHA1s (or None).

Parameters
f:`IO[bytes]`	file-like object to read from, seek'ed to the second line

Returns
`Iterator[tuple[ObjectID, Ref, ObjectID \| None]]`	Undocumented

def set_ref_from_raw(refs: RefsContainer, name: Ref, raw_ref: bytes): ¶

Set a reference from a raw ref value.

This handles both symbolic refs (starting with 'ref: ') and direct ObjectID refs.

Parameters
refs:`RefsContainer`	The RefsContainer to set the ref in
name:`Ref`	The ref name to set
raw_ref:`bytes`	The raw ref value (either a symbolic ref or an ObjectID)

def shorten_ref_name(ref: bytes) -> bytes: ¶

Convert a full ref name to its short form.

Examples

>>> shorten_ref_name(b"refs/heads/master")
b'master'
>>> shorten_ref_name(b"refs/remotes/origin/main")
b'origin/main'
>>> shorten_ref_name(b"refs/tags/v1.0")
b'v1.0'
>>> shorten_ref_name(b"HEAD")
b'HEAD'

Parameters
ref:`bytes`	Full ref name (e.g., b"refs/heads/master")

Returns
`bytes`	Short ref name (e.g., b"master")

def write_packed_refs(f: IO[bytes], packed_refs: Mapping[Ref, ObjectID], peeled_refs: Mapping[Ref, ObjectID] | None = None): ¶

Write a packed refs file.

Parameters
f:`IO[bytes]`	empty file-like object to write to
packed_refs:`Mapping[Ref, ObjectID]`	dict of refname to sha of packed refs to write
peeled_refs:`Mapping[Ref, ObjectID] \| None`	dict of refname to peeled value of sha

BAD_REF_CHARS: set[int] = ¶

Undocumented

Value

set(b'\x7f ~^:?*[')

HEADREF = ¶

Undocumented

Value

Ref(b'HEAD')

LOCAL_BRANCH_PREFIX: bytes = ¶

Undocumented

Value

b'refs/heads/'

LOCAL_NOTES_PREFIX: bytes = ¶

Undocumented

Value

b'refs/notes/'

LOCAL_REMOTE_PREFIX: bytes = ¶

Undocumented

Value

b'refs/remotes/'

LOCAL_REPLACE_PREFIX: bytes = ¶

Undocumented

Value

b'refs/replace/'

LOCAL_TAG_PREFIX: bytes = ¶

Undocumented

Value

b'refs/tags/'

SYMREF: bytes = ¶

Undocumented

Value

b'ref: '

T = ¶

Undocumented

Value

TypeVar('T', dict[Ref, ObjectID], dict[Ref, ObjectID | None])

Ref = ¶

Undocumented

def _import_remote_refs(refs_container: RefsContainer, remote_name: str, refs: Mapping[Ref, ObjectID | None], message: bytes | None = None, prune: bool = False, prune_tags: bool = False): ¶

Undocumented

def _set_default_branch(refs: RefsContainer, origin: bytes, origin_head: bytes | None, branch: bytes | None, ref_message: bytes | None) -> bytes: ¶

Set the default branch.

def _set_head(refs: RefsContainer, head_ref: bytes, ref_message: bytes | None) -> ObjectID | None: ¶

Undocumented

def _set_origin_head(refs: RefsContainer, origin: bytes, origin_head: bytes | None): ¶

Undocumented

def _split_ref_line(line: bytes) -> tuple[ObjectID, Ref]: ¶

Split a single ref line into a tuple of SHA1 and name.