dulwich.refs module

Ref handling.

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

Bases: dulwich.refs.RefsContainer

RefsContainer backed by a simple dict.

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

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
  • message – Message for reflog
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, 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
class dulwich.refs.DiskRefsContainer(path, worktree_path=None, logger=None)

Bases: dulwich.refs.RefsContainer

Refs container that reads refs from disk.

add_if_new(name, ref, committer=None, timestamp=None, timezone=None, message=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: dulwich.refs.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)

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

Parameters:
  • name – Ref name
  • ref – Ref value
  • message – Message for reflog
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, other, committer=None, timestamp=None, timezone=None, message=None, prune=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.
dulwich.refs.check_ref_format(refname)

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