dulwich.repo module

Repository access.

This module contains the base class for git repositories (BaseRepo) and an implementation which uses a repository on local disk (Repo).

class dulwich.repo.BaseRepo(object_store, refs)

Bases: object

Base class for a git repository.

Variables
  • object_store – Dictionary-like object for accessing the objects

  • refs – Dictionary-like object with the refs in this repository

Open a repository.

This shouldn’t be called directly, but rather through one of the base classes, such as MemoryRepo or Repo.

Parameters
  • object_store – Object store to use

  • refs – Refs container to use

do_commit(message=None, committer=None, author=None, commit_timestamp=None, commit_timezone=None, author_timestamp=None, author_timezone=None, tree=None, encoding=None, ref=b'HEAD', merge_heads=None)

Create a new commit.

Parameters
  • message – Commit message

  • committer – Committer fullname

  • author – Author fullname (defaults to committer)

  • commit_timestamp – Commit timestamp (defaults to now)

  • commit_timezone – Commit timestamp timezone (defaults to GMT)

  • author_timestamp – Author timestamp (defaults to commit timestamp)

  • author_timezone – Author timestamp timezone (defaults to commit timestamp timezone)

  • tree – SHA1 of the tree root to use (if not specified the current index will be committed).

  • encoding – Encoding

  • ref – Optional ref to commit to (defaults to current branch)

  • merge_heads – Merge heads (defaults to .git/MERGE_HEADS)

Returns: New commit SHA1

fetch(target, determine_wants=None, progress=None, depth=None)

Fetch objects into another repository.

Parameters
  • target – The target repository

  • determine_wants – Optional function to determine what refs to fetch.

  • progress – Optional progress function

  • depth – Optional shallow fetch depth

Returns: The local refs

fetch_objects(determine_wants, graph_walker, progress, get_tagged=None, depth=None)

Fetch the missing objects required for a set of revisions.

Parameters
  • determine_wants – Function that takes a dictionary with heads and returns the list of heads to fetch.

  • graph_walker – Object that can iterate over the list of revisions to fetch and has an “ack” method that will be called to acknowledge that a revision is present.

  • progress – Simple progress function that will be called with updated progress strings.

  • get_tagged – Function that returns a dict of pointed-to sha -> tag sha for including tags.

  • depth – Shallow fetch depth

Returns: iterator over objects, with __len__ implemented

fetch_pack_data(determine_wants, graph_walker, progress, get_tagged=None, depth=None)

Fetch the pack data required for a set of revisions.

Parameters
  • determine_wants – Function that takes a dictionary with heads and returns the list of heads to fetch.

  • graph_walker – Object that can iterate over the list of revisions to fetch and has an “ack” method that will be called to acknowledge that a revision is present.

  • progress – Simple progress function that will be called with updated progress strings.

  • get_tagged – Function that returns a dict of pointed-to sha -> tag sha for including tags.

  • depth – Shallow fetch depth

Returns: count and iterator over pack data

get_config()

Retrieve the config object.

Returns: ConfigFile object for the .git/config file.

get_config_stack()

Return a config stack for this repository.

This stack accesses the configuration for both this repository itself (.git/config) and the global configuration, which usually lives in ~/.gitconfig.

Returns: Config instance for this repository

get_description()

Retrieve the description for this repository.

Returns: String with the description of the repository

as set by the user.

get_graph_walker(heads=None)

Retrieve a graph walker.

A graph walker is used by a remote repository (or proxy) to find out which objects are present in this repository.

Parameters

heads – Repository heads to use (optional)

Returns: A graph walker object

get_named_file(path)

Get a file from the control dir with a specific name.

Although the filename should be interpreted as a filename relative to the control dir in a disk-based Repo, the object returned need not be pointing to a file in that location.

Parameters

path – The path to the file, relative to the control dir.

Returns: An open file object, or None if the file does not exist.

get_object(sha)

Retrieve the object with the specified SHA.

Parameters

sha – SHA to retrieve

Returns: A ShaFile object :raises KeyError: when the object can not be found

get_parents(sha, commit=None)

Retrieve the parents of a specific commit.

If the specific commit is a graftpoint, the graft parents will be returned instead.

Parameters
  • sha – SHA of the commit for which to retrieve the parents

  • commit – Optional commit matching the sha

Returns: List of parents

get_peeled(ref)

Get the peeled value of a ref.

Parameters

ref – The refname to peel.

Returns: The fully-peeled SHA1 of a tag object, after peeling all

intermediate tags; if the original ref does not point to a tag, this will equal the original SHA1.

get_refs()

Get dictionary with all refs.

Returns: A dict mapping ref names to SHA1s

get_shallow()

Get the set of shallow commits.

Returns: Set of shallow commits.

get_walker(include=None, *args, **kwargs)

Obtain a walker for this repository.

Parameters
  • include – Iterable of SHAs of commits to include along with their ancestors. Defaults to [HEAD]

  • exclude – Iterable of SHAs of commits to exclude along with their ancestors, overriding includes.

  • order – ORDER_* constant specifying the order of results. Anything other than ORDER_DATE may result in O(n) memory usage.

  • reverse – If True, reverse the order of output, requiring O(n) memory.

  • max_entries – The maximum number of entries to yield, or None for no limit.

  • paths – Iterable of file or subtree paths to show entries for.

  • rename_detector – diff.RenameDetector object for detecting renames.

  • follow – If True, follow path across renames/copies. Forces a default rename_detector.

  • since – Timestamp to list commits after.

  • until – Timestamp to list commits before.

  • queue_cls – A class to use for a queue of commits, supporting the iterator protocol. The constructor takes a single argument, the Walker.

Returns: A Walker object

head()

Return the SHA1 pointed at by HEAD.

open_index()

Open the index for this repository.

Raises

NoIndexPresent – If no index is present

Returns: The matching Index

set_description(description)

Set the description for this repository.

Parameters

description – Text to set as description for this repository.

update_shallow(new_shallow, new_unshallow)

Update the list of shallow objects.

Parameters
  • new_shallow – Newly shallow objects

  • new_unshallow – Newly no longer shallow objects

exception dulwich.repo.InvalidUserIdentity(identity)

Bases: Exception

User identity is not of the format ‘user <email>’

class dulwich.repo.MemoryRepo

Bases: dulwich.repo.BaseRepo

Repo that stores refs, objects, and named files in memory.

MemoryRepos are always bare: they have no working tree and no index, since those have a stronger dependency on the filesystem.

get_config()

Retrieve the config object.

Returns: ConfigFile object.

get_description()

Retrieve the description for this repository.

Returns: String with the description of the repository

as set by the user.

get_named_file(path, basedir=None)

Get a file from the control dir with a specific name.

Although the filename should be interpreted as a filename relative to the control dir in a disk-baked Repo, the object returned need not be pointing to a file in that location.

Parameters

path – The path to the file, relative to the control dir.

Returns: An open file object, or None if the file does not exist.

classmethod init_bare(objects, refs)

Create a new bare repository in memory.

Parameters
  • objects – Objects for the new repository, as iterable

  • refs – Refs as dictionary, mapping names to object SHA1s

open_index()

Fail to open index for this repo, since it is bare.

Raises

NoIndexPresent – Raised when no index is present

set_description(description)

Set the description for this repository.

Parameters

description – Text to set as description for this repository.

class dulwich.repo.Repo(root)

Bases: dulwich.repo.BaseRepo

A git repository backed by local disk.

To open an existing repository, call the contructor with the path of the repository.

To create a new repository, use the Repo.init class method.

clone(target_path, mkdir=True, bare=False, origin=b'origin', checkout=None)

Clone this repository.

Parameters
  • target_path – Target path

  • mkdir – Create the target directory

  • bare – Whether to create a bare repository

  • origin – Base name for refs in target repository cloned from this repository

Returns: Created repository as Repo

close()

Close any files opened by this repository.

commondir()

Return the path of the common directory.

For a main working tree, it is identical to controldir().

For a linked working tree, it is the control directory of the main working tree.

controldir()

Return the path of the control directory.

classmethod create(path, mkdir=False)

Create a new bare repository.

path should already exist and be an empty directory.

Parameters

path – Path to create bare repository in

Returns: a Repo instance

classmethod discover(start='.')

Iterate parent directories to discover a repository

Return a Repo object for the first parent directory that looks like a Git repository.

Parameters

start – The directory to start discovery from (defaults to ‘.’)

get_blob_normalizer()

Return a BlobNormalizer object

get_config()

Retrieve the config object.

Returns: ConfigFile object for the .git/config file.

get_description()

Retrieve the description of this repository.

Returns: A string describing the repository or None.

get_named_file(path, basedir=None)

Get a file from the control dir with a specific name.

Although the filename should be interpreted as a filename relative to the control dir in a disk-based Repo, the object returned need not be pointing to a file in that location.

Parameters
  • path – The path to the file, relative to the control dir.

  • basedir – Optional argument that specifies an alternative to the control dir.

Returns: An open file object, or None if the file does not exist.

has_index()

Check if an index is present.

index_path()

Return path to the index file.

classmethod init(path, mkdir=False)

Create a new repository.

Parameters
  • path – Path in which to create the repository

  • mkdir – Whether to create the directory

Returns: Repo instance

classmethod init_bare(path, mkdir=False)

Create a new bare repository.

path should already exist and be an empty directory.

Parameters

path – Path to create bare repository in

Returns: a Repo instance

open_index()

Open the index for this repository.

Raises

NoIndexPresent – If no index is present

Returns: The matching Index

reset_index(tree=None)

Reset the index back to a specific tree.

Parameters

tree – Tree SHA to reset to, None for current HEAD tree.

set_description(description)

Set the description for this repository.

Parameters

description – Text to set as description for this repository.

stage(fs_paths)

Stage a set of paths.

Parameters

fs_paths – List of paths, relative to the repository path

dulwich.repo.check_user_identity(identity)

Verify that a user identity is formatted correctly.

Parameters

identity – User identity bytestring

Raises

InvalidUserIdentity – Raised when identity is invalid

dulwich.repo.get_user_identity(config, kind=None)

Determine the identity to use for new commits.

dulwich.repo.parse_graftpoints(graftpoints)

Convert a list of graftpoints into a dict

Parameters

graftpoints – Iterator of graftpoint lines

Each line is formatted as:

<commit sha1> <parent sha1> [<parent sha1>]*

Resulting dictionary is:

<commit sha1>: [<parent sha1>*]

https://git.wiki.kernel.org/index.php/GraftPoint

dulwich.repo.read_gitfile(f)

Read a .git file.

The first line of the file should start with “gitdir: “

Parameters

f – File-like object to read from

Returns: A path

dulwich.repo.serialize_graftpoints(graftpoints)

Convert a dictionary of grafts into string

The graft dictionary is:

<commit sha1>: [<parent sha1>*]

Each line is formatted as:

<commit sha1> <parent sha1> [<parent sha1>]*

https://git.wiki.kernel.org/index.php/GraftPoint