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