dulwich.refs module

Ref handling.

class dulwich.refs.DictRefsContainer(refs, logger=None)

Bases: RefsContainer

RefsContainer backed by a simple dict.

This container does not support symbolic or packed references and is not threadsafe.

add_if_new(name: bytes, ref: bytes, committer=None, timestamp=None, timezone=None, message: Optional[bytes] = None)

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

Parameters

• name – Ref name

• ref – Ref value

allkeys()

All refs present in this container.

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.

get_peeled(name)

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

Parameters

name – Name of the ref to peel

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.

read_loose_ref(name)

Read a loose reference and return its contents.

Parameters

name – the refname to read

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

not exist.

remove_if_equals(name, old_ref, committer=None, timestamp=None, timezone=None, message=None)

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.

Parameters

• name – The refname to delete.

• old_ref – The old sha the refname must refer to, or None to delete unconditionally.

• message – Message for reflog

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

set_if_equals(name, old_ref, new_ref, committer=None, timestamp=None, timezone=None, message=None)

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.

Parameters

• name – The refname to set.

• old_ref – The old sha the refname must refer to, or None to set unconditionally.

• new_ref – The new sha the refname will refer to.

• message – Message for reflog

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

set_symbolic_ref(name: bytes, other: bytes, committer=None, timestamp=None, timezone=None, message=None)

Make a ref point at another ref.

Parameters

• name – Name of the ref to set

• other – Name of the ref to point at

• message – Optional message

class dulwich.refs.DiskRefsContainer(path, worktree_path=None, logger=None)

Bases: RefsContainer

Refs container that reads refs from disk.

add_if_new(name: bytes, ref: bytes, committer=None, timestamp=None, timezone=None, message: Optional[bytes] = None)

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.

Parameters

• name – The refname to set.

• ref – The new sha the refname will refer to.

• message – Optional message for reflog

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

allkeys()

All refs present in this container.

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.

get_peeled(name)

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

Parameters

name – Name of the ref to peel

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.

read_loose_ref(name)

Read a reference file and return its contents.

If the reference file a symbolic reference, only read the first line of the file. Otherwise, only read the first 40 bytes.

Parameters

name – the refname to read, relative to refpath

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

exist.

Raises

IOError – if any other error occurs

refpath(name)

Return the disk path of a ref.

remove_if_equals(name, old_ref, committer=None, timestamp=None, timezone=None, message=None)

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.

Parameters

• name – The refname to delete.

• old_ref – The old sha the refname must refer to, or None to delete unconditionally.

• message – Optional message

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

set_if_equals(name, old_ref, new_ref, committer=None, timestamp=None, timezone=None, message=None)

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.

Parameters

• name – The refname to set.

• old_ref – The old sha the refname must refer to, or None to set unconditionally.

• new_ref – The new sha the refname will refer to.

• message – Set message for reflog

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

set_symbolic_ref(name, other, committer=None, timestamp=None, timezone=None, message=None)

Make a ref point at another ref.

Parameters

• name – Name of the ref to set

• other – Name of the ref to point at

• message – Optional message to describe the change

subkeys(base)

Refs present in this container under a base.

Parameters

base – The base to return refs under.

Returns: A set of valid refs in this container under the base; the base

prefix is stripped from the ref names returned.

class dulwich.refs.InfoRefsContainer(f)

Bases: RefsContainer

Refs container that reads refs from a info/refs file.

allkeys()

All refs present in this container.

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.

get_peeled(name)

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

Parameters

name – Name of the ref to peel

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.

read_loose_ref(name)

Read a loose reference and return its contents.

Parameters

name – the refname to read

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

not exist.

class dulwich.refs.RefsContainer(logger=None)

Bases: object

A container for refs.

add_if_new(name, ref, committer=None, timestamp=None, timezone=None, message=None)

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

Parameters

• name – Ref name

• ref – Ref value

allkeys()

All refs present in this container.

as_dict(base=None)

Return the contents of this container as a dictionary.

follow(name)

Follow a reference name.

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

references in the chain

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.

get_peeled(name)

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

Parameters

name – Name of the ref to peel

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.

get_symrefs()

Get a dict with all symrefs in this container.

Returns: Dictionary mapping source ref to target ref

import_refs(base: bytes, other: Dict[bytes, bytes], committer: Optional[bytes] = None, timestamp: Optional[bytes] = None, timezone: Optional[bytes] = None, message: Optional[bytes] = None, prune: bool = False)

keys(base=None)

Refs present in this container.

Parameters

base – An optional base to return refs under.

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

packed refs.

read_loose_ref(name)

Read a loose reference and return its contents.

Parameters

name – the refname to read

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

not exist.

read_ref(refname)

Read a reference without following any references.

Parameters

refname – The name of the reference

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

not exist.

remove_if_equals(name, old_ref, committer=None, timestamp=None, timezone=None, message=None)

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.

Parameters

• name – The refname to delete.

• old_ref – The old sha the refname must refer to, or None to delete unconditionally.

• message – Message for reflog

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

set_if_equals(name, old_ref, new_ref, committer=None, timestamp=None, timezone=None, message=None)

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.

Parameters

• name – The refname to set.

• old_ref – The old sha the refname must refer to, or None to set unconditionally.

• new_ref – The new sha the refname will refer to.

• message – Message for reflog

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

set_symbolic_ref(name, other, committer=None, timestamp=None, timezone=None, message=None)

Make a ref point at another ref.

Parameters

• name – Name of the ref to set

• other – Name of the ref to point at

• message – Optional message

subkeys(base)

Refs present in this container under a base.

Parameters

base – The base to return refs under.

Returns: A set of valid refs in this container under the base; the base

prefix is stripped from the ref names returned.

exception dulwich.refs.SymrefLoop(ref, depth)

Bases: Exception

There is a loop between one or more symrefs.

dulwich.refs.check_ref_format(refname: bytes)

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

Parameters

refname – The refname to check

Returns: True if refname is valid, False otherwise

dulwich.refs.is_local_branch(x)

dulwich.refs.parse_symref_value(contents)

Parse a symref value.

Parameters

contents – Contents to parse

Returns: Destination

dulwich.refs.read_info_refs(f)

dulwich.refs.read_packed_refs(f)

Read a packed refs file.

Parameters

f – file-like object to read from

Returns: Iterator over tuples with SHA1s and ref names.

dulwich.refs.read_packed_refs_with_peeled(f)

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 – file-like object to read from, seek’ed to the second line

dulwich.refs.strip_peeled_refs(refs)

Remove all peeled refs

dulwich.refs.write_info_refs(refs, store)

Generate info refs.

dulwich.refs.write_packed_refs(f, packed_refs, peeled_refs=None)

Write a packed refs file.

Parameters

• f – empty file-like object to write to

• packed_refs – dict of refname to sha of packed refs to write

• peeled_refs – dict of refname to peeled value of sha