dulwich.porcelain module

Simple wrapper that provides porcelain-like functions on top of Dulwich.

Currently implemented:

  • archive

  • add

  • branch{_create,_delete,_list}

  • check-ignore

  • checkout

  • clone

  • commit

  • commit-tree

  • daemon

  • describe

  • diff-tree

  • fetch

  • init

  • ls-files

  • ls-remote

  • ls-tree

  • pull

  • push

  • rm

  • remote{_add}

  • receive-pack

  • reset

  • submodule_add

  • submodule_init

  • submodule_list

  • rev-list

  • tag{_create,_delete,_list}

  • upload-pack

  • update-server-info

  • status

  • symbolic-ref

These functions are meant to behave similarly to the git subcommands. Differences in behaviour are considered bugs.

Note: one of the consequences of this is that paths tend to be interpreted relative to the current working directory rather than relative to the repository root.

Functions should generally accept both unicode strings and bytestrings

exception dulwich.porcelain.DivergedBranches(current_sha, new_sha)

Bases: Error

Branches have diverged and fast-forward is not possible.

exception dulwich.porcelain.Error(msg)

Bases: Exception

Porcelain-based error.

class dulwich.porcelain.GitStatus(staged, unstaged, untracked)

Bases: tuple

Create new instance of GitStatus(staged, unstaged, untracked)

staged

Alias for field number 0

unstaged

Alias for field number 1

untracked

Alias for field number 2

class dulwich.porcelain.NoneStream

Bases: RawIOBase

Fallback if stdout or stderr are unavailable, does nothing.

read(size=-1)
readall()

Read until EOF, using multiple read() call.

readinto(b)
write(b)
exception dulwich.porcelain.RemoteExists(msg)

Bases: Error

Raised when the remote already exists.

exception dulwich.porcelain.TimezoneFormatError(msg)

Bases: Error

Raised when the timezone cannot be determined from a given string.

dulwich.porcelain.active_branch(repo)

Return the active branch in the repository, if any.

Parameters

repo – Repository to open

Returns

branch name

Raises

  • KeyError – if the repository does not have a working tree

  • IndexError – if HEAD is floating

dulwich.porcelain.add(repo='.', paths=None)

Add files to the staging area.

Parameters

  • repo – Repository for the files

  • paths – Paths to add. No value passed stages all modified files.

Returns: Tuple with set of added files and ignored files

If the repository contains ignored directories, the returned set will contain the path to an ignored directory (with trailing slash). Individual files within ignored directories will not be returned.

dulwich.porcelain.archive(repo, committish=None, outstream=<_io.BufferedWriter name='<stdout>'>, errstream=<_io.BufferedWriter name='<stderr>'>)

Create an archive.

Parameters

  • repo – Path of repository for which to generate an archive.

  • committish – Commit SHA1 or ref to use

  • outstream – Output stream (defaults to stdout)

  • errstream – Error stream (defaults to stderr)

dulwich.porcelain.branch_create(repo, name, objectish=None, force=False)

Create a branch.

Parameters

  • repo – Path to the repository

  • name – Name of the new branch

  • objectish – Target object to point new branch at (defaults to HEAD)

  • force – Force creation of branch, even if it already exists

dulwich.porcelain.branch_delete(repo, name)

Delete a branch.

Parameters

  • repo – Path to the repository

  • name – Name of the branch

dulwich.porcelain.branch_list(repo)

List all branches.

Parameters

repo – Path to the repository

dulwich.porcelain.check_diverged(repo, current_sha, new_sha)

Check if updating to a sha can be done with fast forwarding.

Parameters

  • repo – Repository object

  • current_sha – Current head sha

  • new_sha – New head sha

dulwich.porcelain.check_ignore(repo, paths, no_index=False)

Debug gitignore files.

Parameters

  • repo – Path to the repository

  • paths – List of paths to check for

  • no_index – Don’t check index

Returns: List of ignored files

dulwich.porcelain.check_mailmap(repo, contact)

Check canonical name and email of contact.

Parameters

  • repo – Path to the repository

  • contact – Contact name and/or email

Returns: Canonical contact data

dulwich.porcelain.clean(repo='.', target_dir=None)

Remove any untracked files from the target directory recursively

Equivalent to running git clean -fd in target_dir.

Parameters

  • repo – Repository where the files may be tracked

  • target_dir – Directory to clean - current directory if None

dulwich.porcelain.clone(source, target=None, bare=False, checkout=None, errstream=<_io.BufferedWriter name='<stderr>'>, outstream=None, origin: ~typing.Optional[str] = 'origin', depth: ~typing.Optional[int] = None, branch: ~typing.Optional[~typing.Union[str, bytes]] = None, config: ~typing.Optional[~dulwich.config.Config] = None, **kwargs)

Clone a local or remote git repository.

Parameters

  • source – Path or URL for source repository

  • target – Path to target repository (optional)

  • bare – Whether or not to create a bare repository

  • checkout – Whether or not to check-out HEAD after cloning

  • errstream – Optional stream to write progress to

  • outstream – Optional stream to write progress to (deprecated)

  • origin – Name of remote from the repository used to clone

  • depth – Depth to fetch at

  • branch – Optional branch or tag to be used as HEAD in the new repository instead of the cloned repository’s HEAD.

  • config – Configuration to use

Returns: The new repository

dulwich.porcelain.commit(repo='.', message=None, author=None, author_timezone=None, committer=None, commit_timezone=None, encoding=None, no_verify=False, signoff=False)

Create a new commit.

Parameters

  • repo – Path to repository

  • message – Optional commit message

  • author – Optional author name and email

  • author_timezone – Author timestamp timezone

  • committer – Optional committer name and email

  • commit_timezone – Commit timestamp timezone

  • no_verify – Skip pre-commit and commit-msg hooks

  • signoff – GPG Sign the commit (bool, defaults to False, pass True to use default GPG key, pass a str containing Key ID to use a specific GPG key)

Returns: SHA1 of the new commit

dulwich.porcelain.commit_decode(commit, contents, default_encoding='utf-8')
dulwich.porcelain.commit_encode(commit, contents, default_encoding='utf-8')
dulwich.porcelain.commit_tree(repo, tree, message=None, author=None, committer=None)

Create a new commit object.

Parameters

  • repo – Path to repository

  • tree – An existing tree object

  • author – Optional author name and email

  • committer – Optional committer name and email

dulwich.porcelain.daemon(path='.', address=None, port=None)

Run a daemon serving Git requests over TCP/IP.

Parameters

  • path – Path to the directory to serve.

  • address – Optional address to listen on (defaults to ::)

  • port – Optional port to listen on (defaults to TCP_GIT_PORT)

dulwich.porcelain.describe(repo, abbrev=7)

Describe the repository version.

Parameters

  • repo – git repository

  • abbrev – number of characters of commit to take, default is 7

Returns: a string description of the current git revision

Examples: “gabcdefh”, “v0.1” or “v0.1-5-gabcdefh”.

dulwich.porcelain.diff_tree(repo, old_tree, new_tree, outstream=<_io.BufferedWriter name='<stdout>'>)

Compares the content and mode of blobs found via two tree objects.

Parameters

  • repo – Path to repository

  • old_tree – Id of old tree

  • new_tree – Id of new tree

  • outstream – Stream to write to

dulwich.porcelain.fetch(repo, remote_location=None, outstream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, errstream=<_io.BufferedWriter name='<stderr>'>, message=None, depth=None, prune=False, prune_tags=False, force=False, **kwargs)

Fetch objects from a remote server.

Parameters

  • repo – Path to the repository

  • remote_location – String identifying a remote server

  • outstream – Output stream (defaults to stdout)

  • errstream – Error stream (defaults to stderr)

  • message – Reflog message (defaults to b”fetch: from <remote_name>”)

  • depth – Depth to fetch at

  • prune – Prune remote removed refs

  • prune_tags – Prune reomte removed tags

Returns

Dictionary with refs on the remote

dulwich.porcelain.find_unique_abbrev(object_store, object_id)

For now, just return 7 characters.

dulwich.porcelain.fsck(repo)

Check a repository.

Parameters

repo – A path to the repository

Returns: Iterator over errors/warnings

dulwich.porcelain.get_branch_remote(repo)

Return the active branch’s remote name, if any.

Parameters

repo – Repository to open

Returns

remote name

Raises

KeyError – if the repository does not have a working tree

dulwich.porcelain.get_object_by_path(repo, path, committish=None)

Get an object by path.

Parameters

  • repo – A path to the repository

  • path – Path to look up

  • committish – Commit to look up path in

Returns: A ShaFile object

dulwich.porcelain.get_remote_repo(repo: Repo, remote_location: Optional[Union[str, bytes]] = None) → Tuple[Optional[str], str]
dulwich.porcelain.get_tree_changes(repo)

Return add/delete/modify changes to tree by comparing index to HEAD.

Parameters

repo – repo path or object

Returns: dict with lists for each type of change

dulwich.porcelain.get_untracked_paths(frompath, basepath, index, exclude_ignored=False, untracked_files='all')

Get untracked paths.

Parameters

  • frompath – Path to walk

  • basepath – Path to compare to

  • index – Index to check against

  • exclude_ignored – Whether to exclude ignored paths

  • untracked_files – How to handle untracked files: - “no”: return an empty list - “all”: return all files in untracked directories - “normal”: Not implemented

Note: ignored directories will never be walked for performance reasons.

If exclude_ignored is False, only the path to an ignored directory will be yielded, no files inside the directory will be returned

dulwich.porcelain.get_user_timezones()

Retrieve local timezone as described in https://raw.githubusercontent.com/git/git/v2.3.0/Documentation/date-formats.txt Returns: A tuple containing author timezone, committer timezone

dulwich.porcelain.init(path='.', bare=False)

Create a new git repository.

Parameters

  • path – Path to repository.

  • bare – Whether to create a bare repository.

Returns: A Repo instance

dulwich.porcelain.log(repo='.', paths=None, outstream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, max_entries=None, reverse=False, name_status=False)

Write commit logs.

Parameters

  • repo – Path to repository

  • paths – Optional set of specific paths to print entries for

  • outstream – Stream to write log output to

  • reverse – Reverse order in which entries are printed

  • name_status – Print name status

  • max_entries – Optional maximum number of entries to display

dulwich.porcelain.ls_files(repo)

List all files in an index.

dulwich.porcelain.ls_remote(remote, config: Optional[Config] = None, **kwargs)

List the refs in a remote.

Parameters

  • remote – Remote repository location

  • config – Configuration to use

Returns

Dictionary with remote refs

dulwich.porcelain.ls_tree(repo, treeish=b'HEAD', outstream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, recursive=False, name_only=False)

List contents of a tree.

Parameters

  • repo – Path to the repository

  • treeish – Tree id to list

  • outstream – Output stream (defaults to stdout)

  • recursive – Whether to recursively list files

  • name_only – Only print item name

dulwich.porcelain.open_repo(path_or_repo)

Open an argument that can be a repository or a path for a repository.

dulwich.porcelain.open_repo_closing(path_or_repo)

Open an argument that can be a repository or a path for a repository. returns a context manager that will close the repo on exit if the argument is a path, else does nothing if the argument is a repo.

dulwich.porcelain.pack_objects(repo, object_ids, packf, idxf, delta_window_size=None)

Pack objects into a file.

Parameters

  • repo – Path to the repository

  • object_ids – List of object ids to write

  • packf – File-like object to write to

  • idxf – File-like object to write to (can be None)

dulwich.porcelain.parse_timezone_format(tz_str)

Parse given string and attempt to return a timezone offset.

Different formats are considered in the following order:

  • Git internal format: <unix timestamp> <timezone offset>

  • RFC 2822: e.g. Mon, 20 Nov 1995 19:12:08 -0500

  • ISO 8601: e.g. 1995-11-20T19:12:08-0500

Parameters

tz_str – datetime string

Returns: Timezone offset as integer :raises TimezoneFormatError: if timezone information cannot be extracted

dulwich.porcelain.path_to_tree_path(repopath, path, tree_encoding='utf-8')

Convert a path to a path usable in an index, e.g. bytes and relative to the repository root.

Parameters

  • repopath – Repository path, absolute or relative to the cwd

  • path – A path, absolute or relative to the cwd

Returns: A path formatted for use in e.g. an index

dulwich.porcelain.print_commit(commit, decode, outstream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Write a human-readable commit log entry.

Parameters

  • commit – A Commit object

  • outstream – A stream file to write to

dulwich.porcelain.print_name_status(changes)

Print a simple status summary, listing changed files.

dulwich.porcelain.print_tag(tag, decode, outstream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Write a human-readable tag.

Parameters

  • tag – A Tag object

  • decode – Function for decoding bytes to unicode string

  • outstream – A stream to write to

dulwich.porcelain.pull(repo, remote_location=None, refspecs=None, outstream=<_io.BufferedWriter name='<stdout>'>, errstream=<_io.BufferedWriter name='<stderr>'>, fast_forward=True, force=False, **kwargs)

Pull from remote via dulwich.client

Parameters

  • repo – Path to repository

  • remote_location – Location of the remote

  • refspecs – refspecs to fetch

  • outstream – A stream file to write to output

  • errstream – A stream file to write to errors

dulwich.porcelain.push(repo, remote_location=None, refspecs=None, outstream=<_io.BufferedWriter name='<stdout>'>, errstream=<_io.BufferedWriter name='<stderr>'>, force=False, **kwargs)

Remote push with dulwich via dulwich.client

Parameters

  • repo – Path to repository

  • remote_location – Location of the remote

  • refspecs – Refs to push to remote

  • outstream – A stream file to write output

  • errstream – A stream file to write errors

  • force – Force overwriting refs

dulwich.porcelain.receive_pack(path='.', inf=None, outf=None)

Receive a pack file after negotiating its contents using smart protocol.

Parameters

  • path – Path to the repository

  • inf – Input stream to communicate with client

  • outf – Output stream to communicate with client

dulwich.porcelain.remote_add(repo: Repo, name: Union[bytes, str], url: Union[bytes, str])

Add a remote.

Parameters

  • repo – Path to the repository

  • name – Remote name

  • url – Remote URL

dulwich.porcelain.remote_remove(repo: Repo, name: Union[bytes, str])

Remove a remote

Parameters

  • repo – Path to the repository

  • name – Remote name

dulwich.porcelain.remove(repo='.', paths=None, cached=False)

Remove files from the staging area.

Parameters

  • repo – Repository for the files

  • paths – Paths to remove

dulwich.porcelain.repack(repo)

Repack loose files in a repository.

Currently this only packs loose objects.

Parameters

repo – Path to the repository

dulwich.porcelain.reset(repo, mode, treeish='HEAD')

Reset current HEAD to the specified state.

Parameters

  • repo – Path to repository

  • mode – Mode (“hard”, “soft”, “mixed”)

  • treeish – Treeish to reset to

dulwich.porcelain.reset_file(repo, file_path: str, target: bytes = b'HEAD', symlink_fn=None)

Reset the file to specific commit or branch.

Parameters

  • repo – dulwich Repo object

  • file_path – file to reset, relative to the repository path

  • target – branch or commit or b’HEAD’ to reset

dulwich.porcelain.rev_list(repo, commits, outstream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Lists commit objects in reverse chronological order.

Parameters

  • repo – Path to repository

  • commits – Commits over which to iterate

  • outstream – Stream to write to

dulwich.porcelain.rm(repo='.', paths=None, cached=False)

Remove files from the staging area.

Parameters

  • repo – Repository for the files

  • paths – Paths to remove

dulwich.porcelain.show(repo='.', objects=None, outstream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, default_encoding='utf-8')

Print the changes in a commit.

Parameters

  • repo – Path to repository

  • objects – Objects to show (defaults to [HEAD])

  • outstream – Stream to write to

  • default_encoding – Default encoding to use if none is set in the commit

dulwich.porcelain.show_blob(repo, blob, decode, outstream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Write a blob to a stream.

Parameters

  • repo – A Repo object

  • blob – A Blob object

  • decode – Function for decoding bytes to unicode string

  • outstream – A stream file to write to

dulwich.porcelain.show_commit(repo, commit, decode, outstream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Show a commit to a stream.

Parameters

  • repo – A Repo object

  • commit – A Commit object

  • decode – Function for decoding bytes to unicode string

  • outstream – Stream to write to

dulwich.porcelain.show_object(repo, obj, decode, outstream)
dulwich.porcelain.show_tag(repo, tag, decode, outstream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Print a tag to a stream.

Parameters

  • repo – A Repo object

  • tag – A Tag object

  • decode – Function for decoding bytes to unicode string

  • outstream – Stream to write to

dulwich.porcelain.show_tree(repo, tree, decode, outstream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Print a tree to a stream.

Parameters

  • repo – A Repo object

  • tree – A Tree object

  • decode – Function for decoding bytes to unicode string

  • outstream – Stream to write to

dulwich.porcelain.stash_drop(repo, index)

Drop a stash from the stack.

dulwich.porcelain.stash_list(repo)

List all stashes in a repository.

dulwich.porcelain.stash_pop(repo, index)

Pop a stash from the stack.

dulwich.porcelain.stash_push(repo)

Push a new stash onto the stack.

dulwich.porcelain.status(repo='.', ignored=False, untracked_files='all')

Returns staged, unstaged, and untracked changes relative to the HEAD.

Parameters

  • repo – Path to repository or repository object

  • ignored – Whether to include ignored files in untracked

  • untracked_files –

    How to handle untracked files, defaults to “all”:

    ”no”: do not return untracked files “all”: include all files in untracked directories

    Using untracked_files=”no” can be faster than “all” when the worktreee

    contains many untracked files/directories.

Note: untracked_files=”normal” (git’s default) is not implemented.

Returns: GitStatus tuple,

staged - dict with lists of staged paths (diff index/HEAD) unstaged - list of unstaged paths (diff index/working-tree) untracked - list of untracked, un-ignored & non-.git paths

dulwich.porcelain.submodule_add(repo, url, path=None, name=None)

Add a new submodule.

Parameters

  • repo – Path to repository

  • url – URL of repository to add as submodule

  • path – Path where submodule should live

dulwich.porcelain.submodule_init(repo)

Initialize submodules.

Parameters

repo – Path to repository

dulwich.porcelain.submodule_list(repo)

List submodules.

Parameters

repo – Path to repository

dulwich.porcelain.symbolic_ref(repo, ref_name, force=False)

Set git symbolic ref into HEAD.

Parameters

  • repo – path to the repository

  • ref_name – short name of the new ref

  • force – force settings without checking if it exists in refs/heads

dulwich.porcelain.tag_create(repo, tag, author=None, message=None, annotated=False, objectish='HEAD', tag_time=None, tag_timezone=None, sign=False, encoding='utf-8')

Creates a tag in git via dulwich calls:

Parameters

  • repo – Path to repository

  • tag – tag string

  • author – tag author (optional, if annotated is set)

  • message – tag message (optional)

  • annotated – whether to create an annotated tag

  • objectish – object the tag should point at, defaults to HEAD

  • tag_time – Optional time for annotated tag

  • tag_timezone – Optional timezone for annotated tag

  • sign – GPG Sign the tag (bool, defaults to False, pass True to use default GPG key, pass a str containing Key ID to use a specific GPG key)

dulwich.porcelain.tag_delete(repo, name)

Remove a tag.

Parameters

  • repo – Path to repository

  • name – Name of tag to remove

dulwich.porcelain.tag_list(repo, outstream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

List all tags.

Parameters

  • repo – Path to repository

  • outstream – Stream to write tags to

dulwich.porcelain.update_head(repo, target, detached=False, new_branch=None)

Update HEAD to point at a new branch/commit.

Note that this does not actually update the working tree.

Parameters

  • repo – Path to the repository

  • detached – Create a detached head

  • target – Branch or committish to switch to

  • new_branch – New branch to create

dulwich.porcelain.update_server_info(repo='.')

Update server info files for a repository.

Parameters

repo – path to the repository

dulwich.porcelain.upload_pack(path='.', inf=None, outf=None)

Upload a pack file after negotiating its contents using smart protocol.

Parameters

  • path – Path to the repository

  • inf – Input stream to communicate with client

  • outf – Output stream to communicate with client

dulwich.porcelain.web_daemon(path='.', address=None, port=None)

Run a daemon serving Git requests over HTTP.

Parameters

  • path – Path to the directory to serve

  • address – Optional address to listen on (defaults to ::)

  • port – Optional port to listen on (defaults to 80)

dulwich.porcelain.write_tree(repo)

Write a tree object from the index.

Parameters

repo – Repository for which to write tree

Returns: tree id for the tree that was written