dulwich.porcelain

module documentation

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

Class	`NoneStream`	Fallback if stdout or stderr are unavailable, does nothing.
Exception	`DivergedBranches`	Branches have diverged and fast-forward is not possible.
Exception	`Error`	Porcelain-based error.
Exception	`RemoteExists`	Raised when the remote already exists.
Exception	`TimezoneFormatError`	Raised when the timezone cannot be determined from a given string.
Function	`active_branch`	Return the active branch in the repository, if any.
Function	`add`	Add files to the staging area.
Function	`archive`	Create an archive.
Function	`branch_create`	Create a branch.
Function	`branch_delete`	Delete a branch.
Function	`branch_list`	List all branches.
Function	`check_diverged`	Check if updating to a sha can be done with fast forwarding.
Function	`check_ignore`	Debug gitignore files.
Function	`check_mailmap`	Check canonical name and email of contact.
Function	`clean`	Remove any untracked files from the target directory recursively
Function	`clone`	Clone a local or remote git repository.
Function	`commit`	Create a new commit.
Function	`commit_decode`	Undocumented
Function	`commit_encode`	Undocumented
Function	`commit_tree`	Create a new commit object.
Function	`daemon`	Run a daemon serving Git requests over TCP/IP.
Function	`describe`	Describe the repository version.
Function	`diff_tree`	Compares the content and mode of blobs found via two tree objects.
Function	`fetch`	Fetch objects from a remote server.
Function	`find_unique_abbrev`	For now, just return 7 characters.
Function	`fsck`	Check a repository.
Function	`get_branch_remote`	Return the active branch's remote name, if any.
Function	`get_object_by_path`	Get an object by path.
Function	`get_remote_repo`	Undocumented
Function	`get_tree_changes`	Return add/delete/modify changes to tree by comparing index to HEAD.
Function	`get_untracked_paths`	Get untracked paths.
Function	`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
Function	`init`	Create a new git repository.
Function	`log`	Write commit logs.
Function	`ls_files`	List all files in an index.
Function	`ls_remote`	List the refs in a remote.
Function	`ls_tree`	List contents of a tree.
Function	`open_repo`	Open an argument that can be a repository or a path for a repository.
Function	`open_repo_closing`	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.
Function	`pack_objects`	Pack objects into a file.
Function	`parse_timezone_format`	Parse given string and attempt to return a timezone offset.
Function	`path_to_tree_path`	Convert a path to a path usable in an index, e.g. bytes and relative to the repository root.
Function	`print_commit`	Write a human-readable commit log entry.
Function	`print_name_status`	Print a simple status summary, listing changed files.
Function	`print_tag`	Write a human-readable tag.
Function	`pull`	Pull from remote via dulwich.client
Function	`push`	Remote push with dulwich via dulwich.client
Function	`receive_pack`	Receive a pack file after negotiating its contents using smart protocol.
Function	`remote_add`	Add a remote.
Function	`remote_remove`	Remove a remote
Function	`remove`	Remove files from the staging area.
Function	`repack`	Repack loose files in a repository.
Function	`reset`	Reset current HEAD to the specified state.
Function	`reset_file`	Reset the file to specific commit or branch.
Function	`rev_list`	Lists commit objects in reverse chronological order.
Function	`show`	Print the changes in a commit.
Function	`show_blob`	Write a blob to a stream.
Function	`show_commit`	Show a commit to a stream.
Function	`show_object`	Undocumented
Function	`show_tag`	Print a tag to a stream.
Function	`show_tree`	Print a tree to a stream.
Function	`stash_drop`	Drop a stash from the stack.
Function	`stash_list`	List all stashes in a repository.
Function	`stash_pop`	Pop a stash from the stack.
Function	`stash_push`	Push a new stash onto the stack.
Function	`status`	Returns staged, unstaged, and untracked changes relative to the HEAD.
Function	`submodule_add`	Add a new submodule.
Function	`submodule_init`	Initialize submodules.
Function	`submodule_list`	List submodules.
Function	`symbolic_ref`	Set git symbolic ref into HEAD.
Function	`tag_create`	Creates a tag in git via dulwich calls:
Function	`tag_delete`	Remove a tag.
Function	`tag_list`	List all tags.
Function	`update_head`	Update HEAD to point at a new branch/commit.
Function	`update_server_info`	Update server info files for a repository.
Function	`upload_pack`	Upload a pack file after negotiating its contents using smart protocol.
Function	`web_daemon`	Run a daemon serving Git requests over HTTP.
Function	`write_tree`	Write a tree object from the index.
Constant	`DEFAULT_ENCODING`	Undocumented
Variable	`default_bytes_err_stream`	Undocumented
Variable	`default_bytes_out_stream`	Undocumented
Variable	`GitStatus`	Undocumented
Function	`_canonical_part`	Undocumented
Function	`_is_subdir`	Check whether subdir is parentdir or a subdir of parentdir
Function	`_make_branch_ref`	Undocumented
Function	`_make_tag_ref`	Undocumented
Function	`_noop_context_manager`	Context manager that has the same api as closing but does nothing.
Function	`_walk_working_dir_paths`	Get path, is_dir for files in working dir from frompath

def 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

def add(repo='.', paths=None): ¶

Add files to the staging area.

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.

Parameters
repo	Repository for the files
paths	Paths to add. No value passed stages all modified files.

def archive(repo, committish=None, outstream=default_bytes_out_stream, errstream=default_bytes_err_stream): ¶

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)

def 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

def branch_delete(repo, name): ¶

Delete a branch.

Parameters
repo	Path to the repository
name	Name of the branch

def branch_list(repo): ¶

List all branches.

Parameters
repo	Path to the repository

def 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

def check_ignore(repo, paths, no_index=False): ¶

Debug gitignore files.

Returns: List of ignored files

Parameters
repo	Path to the repository
paths	List of paths to check for
no_index	Don't check index

def check_mailmap(repo, contact): ¶

Check canonical name and email of contact.

Returns: Canonical contact data

Parameters
repo	Path to the repository
contact	Contact name and/or email

def 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

def clone(source, target=None, bare=False, checkout=None, errstream=default_bytes_err_stream, outstream=None, origin='origin', depth=None, branch=None, config=None, **kwargs): ¶

Clone a local or remote git repository.

Returns: The new 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:`Optional[str]`	Name of remote from the repository used to clone
depth:`Optional[int]`	Depth to fetch at
branch:`Optional[Union[str, bytes]]`	Optional branch or tag to be used as HEAD in the new repository instead of the cloned repository's HEAD.
config:`Optional[Config]`	Configuration to use
**kwargs	Undocumented

def 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.

Returns: SHA1 of the 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
encoding	Undocumented
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)

def commit_decode(commit, contents, default_encoding=DEFAULT_ENCODING): ¶

Undocumented

def commit_encode(commit, contents, default_encoding=DEFAULT_ENCODING): ¶

Undocumented

def 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
message	Undocumented
author	Optional author name and email
committer	Optional committer name and email

def 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)

def describe(repo, abbrev=7): ¶

Describe the repository version.

Returns: a string description of the current git revision

Examples: "gabcdefh", "v0.1" or "v0.1-5-gabcdefh".

Parameters
repo	git repository
abbrev	number of characters of commit to take, default is 7

def diff_tree(repo, old_tree, new_tree, outstream=default_bytes_out_stream): ¶

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

def fetch(repo, remote_location=None, outstream=sys.stdout, errstream=default_bytes_err_stream, 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
force	Undocumented
**kwargs	Undocumented
Returns
Dictionary with refs on the remote

def find_unique_abbrev(object_store, object_id): ¶

For now, just return 7 characters.

def fsck(repo): ¶

Check a repository.

Returns: Iterator over errors/warnings

Parameters
repo	A path to the repository

def 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

def get_object_by_path(repo, path, committish=None): ¶

Get an object by path.

Returns: A ShaFile object

Parameters
repo	A path to the repository
path	Path to look up
committish	Commit to look up path in

def get_remote_repo(repo, remote_location=None): ¶

Undocumented

Parameters
repo:`Repo`	Undocumented
remote_location:`Optional[Union[str, bytes]]`	Undocumented
Returns
`Tuple[Optional[str], str]`	Undocumented

def get_tree_changes(repo): ¶

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

Returns: dict with lists for each type of change

Parameters
repo	repo path or object

def get_untracked_paths(frompath, basepath, index, exclude_ignored=False, untracked_files='all'): ¶

Get untracked paths.

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

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

def 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

def init(path='.', bare=False): ¶

Create a new git repository.

Returns: A Repo instance

Parameters
path	Path to repository.
bare	Whether to create a bare repository.

def log(repo='.', paths=None, outstream=sys.stdout, 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
max_entries	Optional maximum number of entries to display
reverse	Reverse order in which entries are printed
name_status	Print name status

def ls_files(repo): ¶

List all files in an index.

def ls_remote(remote, config=None, **kwargs): ¶

List the refs in a remote.

Parameters
remote	Remote repository location
config:`Optional[Config]`	Configuration to use
**kwargs	Undocumented
Returns
Dictionary with remote refs

def ls_tree(repo, treeish=b'HEAD', outstream=sys.stdout, 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

def open_repo(path_or_repo): ¶

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

def 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.

def 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)
delta_window_size	Undocumented

def 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

Returns: Timezone offset as integer

Parameters
tz_str	datetime string
Raises
`TimezoneFormatError`	if timezone information cannot be extracted

def path_to_tree_path(repopath, path, tree_encoding=DEFAULT_ENCODING): ¶

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

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

Parameters
repopath	Repository path, absolute or relative to the cwd
path	A path, absolute or relative to the cwd
tree_encoding	Undocumented

def print_commit(commit, decode, outstream=sys.stdout): ¶

Write a human-readable commit log entry.

Parameters
commit	A `Commit` object
decode	Undocumented
outstream	A stream file to write to

def print_name_status(changes): ¶

Print a simple status summary, listing changed files.

def print_tag(tag, decode, outstream=sys.stdout): ¶

Write a human-readable tag.

Parameters
tag	A `Tag` object
decode	Function for decoding bytes to unicode string
outstream	A stream to write to

def pull(repo, remote_location=None, refspecs=None, outstream=default_bytes_out_stream, errstream=default_bytes_err_stream, 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
fast_forward	Undocumented
force	Undocumented
**kwargs	Undocumented

def push(repo, remote_location=None, refspecs=None, outstream=default_bytes_out_stream, errstream=default_bytes_err_stream, 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
**kwargs	Undocumented

def 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

def remote_add(repo, name, url): ¶

Add a remote.

Parameters
repo:`Repo`	Path to the repository
name:`Union[bytes, str]`	Remote name
url:`Union[bytes, str]`	Remote URL

def remote_remove(repo, name): ¶

Remove a remote

Parameters
repo:`Repo`	Path to the repository
name:`Union[bytes, str]`	Remote name

def remove(repo='.', paths=None, cached=False): ¶

Remove files from the staging area.

Parameters
repo	Repository for the files
paths	Paths to remove
cached	Undocumented

def repack(repo): ¶

Repack loose files in a repository.

Currently this only packs loose objects.

Parameters
repo	Path to the repository

def 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

def reset_file(repo, file_path, target=b'HEAD', symlink_fn=None): ¶

Reset the file to specific commit or branch.

Parameters
repo	dulwich Repo object
file_path:`str`	file to reset, relative to the repository path
target:`bytes`	branch or commit or b'HEAD' to reset
symlink_fn	Undocumented

def rev_list(repo, commits, outstream=sys.stdout): ¶

Lists commit objects in reverse chronological order.

Parameters
repo	Path to repository
commits	Commits over which to iterate
outstream	Stream to write to

def show(repo='.', objects=None, outstream=sys.stdout, default_encoding=DEFAULT_ENCODING): ¶

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

def show_blob(repo, blob, decode, outstream=sys.stdout): ¶

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

def show_commit(repo, commit, decode, outstream=sys.stdout): ¶

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

def show_object(repo, obj, decode, outstream): ¶

Undocumented

def show_tag(repo, tag, decode, outstream=sys.stdout): ¶

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

def show_tree(repo, tree, decode, outstream=sys.stdout): ¶

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

def stash_drop(repo, index): ¶

Drop a stash from the stack.

def stash_list(repo): ¶

List all stashes in a repository.

def stash_pop(repo, index): ¶

Pop a stash from the stack.

def stash_push(repo): ¶

Push a new stash onto the stack.

def status(repo='.', ignored=False, untracked_files='all'): ¶

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

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

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.

def 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
name	Undocumented

def submodule_init(repo): ¶

Initialize submodules.

Parameters
repo	Path to repository

def submodule_list(repo): ¶

List submodules.

Parameters
repo	Path to repository

def 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

def tag_create(repo, tag, author=None, message=None, annotated=False, objectish='HEAD', tag_time=None, tag_timezone=None, sign=False, encoding=DEFAULT_ENCODING): ¶

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)
encoding	Undocumented

def tag_delete(repo, name): ¶

Remove a tag.

Parameters
repo	Path to repository
name	Name of tag to remove

def tag_list(repo, outstream=sys.stdout): ¶

List all tags.

Parameters
repo	Path to repository
outstream	Stream to write tags to

def 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
target	Branch or committish to switch to
detached	Create a detached head
new_branch	New branch to create

def update_server_info(repo='.'): ¶

Update server info files for a repository.

Parameters
repo	path to the repository

def 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

def 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)

def write_tree(repo): ¶

Write a tree object from the index.

Returns: tree id for the tree that was written

Parameters
repo	Repository for which to write tree

DEFAULT_ENCODING: str = ¶

Undocumented

Value

'utf-8'

default_bytes_err_stream = ¶

Undocumented

default_bytes_out_stream = ¶

Undocumented

GitStatus = ¶

Undocumented

def _canonical_part(url): ¶

Undocumented

Parameters
url:`str`	Undocumented
Returns
`str`	Undocumented

def _is_subdir(subdir, parentdir): ¶

Check whether subdir is parentdir or a subdir of parentdir

If parentdir or subdir is a relative path, it will be disamgibuated relative to the pwd.

def _make_branch_ref(name): ¶

Undocumented

def _make_tag_ref(name): ¶

Undocumented

@contextmanager
def _noop_context_manager(obj): ¶

Context manager that has the same api as closing but does nothing.

def _walk_working_dir_paths(frompath, basepath, prune_dirnames=None): ¶

Get path, is_dir for files in working dir from frompath

Parameters
frompath	Path to begin walk
basepath	Path to compare to
prune_dirnames	Optional callback to prune dirnames during os.walk dirnames will be set to result of prune_dirnames(dirpath, dirnames)