dulwich.porcelain

package documentation

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

Currently implemented:

am
apply_patch
archive
add
bisect{_start,_bad,_good,_skip,_reset,_log,_replay}
branch{_create,_delete,_list}
check_ignore
checkout
checkout_branch
clone
cone mode{_init, _set, _add}
commit
commit_tree
daemon
describe
diff_tree
fetch
filter_branch
for_each_ref
grep
init
interpret_trailers
ls_files
ls_remote
ls_tree
mailsplit
merge
merge_tree
mv/move
prune
pull
push
rm
remote{_add}
receive_pack
replace{_create,_delete,_list}
rerere{_status,_diff,_forget,_clear,_gc}
reset
revert
sparse_checkout
submodule_add
submodule_init
submodule_list
rev_list
tag{_create,_delete,_list}
upload_pack
update_server_info
var
write_commit_graph
status
shortlog
symbolic_ref
worktree{_add,_list,_remove,_prune,_lock,_unlock,_move}

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

Module	`lfs`	Porcelain functions for Git LFS support.
Module	`notes`	Porcelain-like interface for Git notes.
Module	`submodule`	Porcelain functions for working with submodules.
Module	`subtree`	Porcelain for git subtree operations.
Module	`tag`	Porcelain-like tag functions for Dulwich.
Module	`worktree`	Porcelain-like interface for Git worktrees.

From __init__.py:

Class	`CountObjectsResult`	Result of counting objects in a repository.
Class	`NoneStream`	Fallback if stdout or stderr are unavailable, does nothing.
Class	`TransportKwargs`	Keyword arguments accepted by get_transport_and_path.
Exception	`CheckoutError`	Indicates that a checkout cannot be performed.
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	`am`	Apply patches from mailbox-style email messages, creating commits.
Function	`am_abort`	Abort the current am and restore the original state.
Function	`am_continue`	Continue applying patches after resolving a conflict.
Function	`am_quit`	Quit the current am without reverting changes.
Function	`am_skip`	Skip the current patch and continue with remaining patches.
Function	`annotate`	Annotate the history of a file.
Function	`apply_patch`	Apply a patch to the working tree and/or index.
Function	`archive`	Create an archive.
Function	`bisect_bad`	Mark a commit as bad.
Function	`bisect_good`	Mark a commit as good.
Function	`bisect_log`	Get the bisect log.
Function	`bisect_replay`	Replay a bisect log.
Function	`bisect_reset`	Reset bisect state and return to original branch/commit.
Function	`bisect_skip`	Skip one or more commits.
Function	`bisect_start`	Start a new bisect session.
Function	`branch_create`	Create a branch.
Function	`branch_delete`	Delete a branch.
Function	`branch_list`	List all branches.
Function	`branch_remotes_list`	List the short names of all remote branches.
Function	`branches_containing`	List branches that contain the specified commit.
Function	`cat_file_content`	Get the raw content of a Git object.
Function	`cat_file_size`	Get the size of a Git object.
Function	`cat_file_type`	Get the type of a Git object.
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	`checkout`	Switch to a branch or commit, updating both HEAD and the working tree.
Function	`cherry`	Find commits not merged upstream.
Function	`cherry_pick`	Cherry-pick a commit onto the current branch.
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`	Decode commit contents using the commit's encoding or default.
Function	`commit_encode`	Encode commit contents using the commit's encoding or default.
Function	`commit_tree`	Create a new commit object.
Function	`cone_mode_add`	Add new directories to the existing 'cone-mode' sparse-checkout patterns.
Function	`cone_mode_disable`	Disable sparse checkout and restore all files.
Function	`cone_mode_init`	Initialize a repository to use sparse checkout in 'cone' mode.
Function	`cone_mode_list`	List current sparse-checkout patterns.
Function	`cone_mode_set`	Overwrite the existing 'cone-mode' sparse patterns with a new set of directories.
Function	`count_objects`	Count unpacked objects and their disk usage.
Function	`daemon`	Run a daemon serving Git requests over TCP/IP.
Function	`describe`	Describe the repository version.
Function	`diff`	Show diff.
Function	`diff_tree`	Compares the content and mode of blobs found via two tree objects.
Function	`fetch`	Fetch objects from a remote server.
Function	`filter_branch`	Rewrite branch history by creating new commits with filtered properties.
Function	`filter_branches_by_pattern`	Filter branches by fnmatch pattern.
Function	`find_unique_abbrev`	Find the shortest unique abbreviation for an object ID.
Function	`for_each_ref`	Iterate over all refs that match the (optional) pattern.
Function	`format_patch`	Generate patches suitable for git am.
Function	`fsck`	Check a repository.
Function	`gc`	Run garbage collection on a repository.
Function	`get_branch_merge`	Return the branch's merge reference (upstream branch), if any.
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`	Get the remote repository information.
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 git documentation.
Function	`grep`	Search for a pattern in tracked files.
Function	`hash_object`	Compute object ID and optionally write to object store.
Function	`independent_commits`	Filter commits to only those that are not reachable from others.
Function	`init`	Create a new git repository.
Function	`interpret_trailers`	Parse and manipulate trailers in a commit message.
Function	`is_ancestor`	Check if one commit is an ancestor of another.
Function	`is_interactive_rebase`	Check if an interactive rebase is in progress.
Function	`lfs_clean`	Clean a file by converting it to an LFS pointer.
Function	`lfs_fetch`	Fetch LFS objects from remote.
Function	`lfs_init`	Initialize Git LFS in a repository.
Function	`lfs_ls_files`	List files tracked by Git LFS.
Function	`lfs_migrate`	Migrate files to Git LFS.
Function	`lfs_pointer_check`	Check if files are valid LFS pointers.
Function	`lfs_pull`	Pull LFS objects for current checkout.
Function	`lfs_push`	Push LFS objects to remote.
Function	`lfs_smudge`	Smudge an LFS pointer by retrieving the actual content.
Function	`lfs_status`	Show status of LFS files.
Function	`lfs_track`	Track file patterns with Git LFS.
Function	`lfs_untrack`	Untrack file patterns from Git LFS.
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	`mailinfo`	Extract patch information from an email message.
Function	`mailsplit`	Split an mbox file or Maildir into individual message files.
Function	`maintenance_register`	Register a repository for background maintenance.
Function	`maintenance_run`	Run maintenance tasks on a repository.
Function	`maintenance_unregister`	Unregister a repository from background maintenance.
Function	`merge`	Merge one or more commits into the current branch.
Function	`merge_base`	Find the best common ancestor(s) between commits.
Function	`merge_tree`	Perform a three-way tree merge without touching the working directory.
Function	`merged_branches`	List branches that have been merged into the current branch.
Function	`mktag`	Create a tag object from raw tag data.
Function	`mv`	Move or rename a file, directory, or symlink.
Function	`no_merged_branches`	List branches that have been merged into the current branch.
Function	`notes_add`	Add or update a note for an object.
Function	`notes_list`	List all notes in a notes ref.
Function	`notes_remove`	Remove a note for an object.
Function	`notes_show`	Show the note for an object.
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.
Function	`pack_objects`	Pack objects into a file.
Function	`pack_refs`	Pack loose references into packed-refs 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_only`	Print only the names of changed files.
Function	`print_name_status`	Print a simple status summary, listing changed files.
Function	`print_oneline`	Write a single-line commit log entry.
Function	`print_stat`	Write a diffstat summary for a commit.
Function	`print_tag`	Write a human-readable tag.
Function	`prune`	Prune/clean up a repository's object store.
Function	`pull`	Pull from remote via dulwich.client.
Function	`push`	Remote push with dulwich via dulwich.client.
Function	`rebase`	Rebase commits onto another branch.
Function	`receive_pack`	Receive a pack file after negotiating its contents using smart protocol.
Function	`reflog`	Show reflog entries for a reference or all references.
Function	`reflog_delete`	Delete a specific reflog entry.
Function	`reflog_expire`	Expire reflog entries based on age and reachability.
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	`replace_create`	Create a replacement ref to replace one object with another.
Function	`replace_delete`	Delete a replacement ref.
Function	`replace_list`	List all replacement refs.
Function	`rerere`	Record current conflict resolutions and apply known resolutions.
Function	`rerere_clear`	Clear all recorded rerere resolutions.
Function	`rerere_diff`	Show differences for recorded rerere conflicts.
Function	`rerere_forget`	Forget recorded rerere resolutions for a pathspec.
Function	`rerere_gc`	Garbage collect old rerere resolutions.
Function	`rerere_status`	Get the status of all conflicts in the rerere cache.
Function	`reset`	Reset current HEAD to the specified state.
Function	`reset_file`	Reset the file to specific commit or branch.
Function	`restore`	Restore working tree files.
Function	`rev_list`	Lists commit objects in reverse chronological order.
Function	`rev_parse`	Parse a revision string and return the object SHA.
Function	`revert`	Revert one or more commits.
Function	`set_branch_tracking`	Set up branch tracking configuration.
Function	`shortlog`	Summarize commits by author, like git shortlog.
Function	`show`	Print the changes in a commit.
Function	`show_blob`	Write a blob to a stream.
Function	`show_branch`	Display branches and their commits.
Function	`show_commit`	Show a commit to a stream.
Function	`show_index`	Show the contents of a pack index file.
Function	`show_object`	Show details of a git object.
Function	`show_ref`	List references in a local repository.
Function	`show_tag`	Print a tag to a stream.
Function	`show_tree`	Print a tree to a stream.
Function	`sparse_checkout`	Perform a sparse checkout in the repository (either 'full' or 'cone mode').
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	`stripspace`	Strip unnecessary whitespace from text.
Function	`submodule_add`	Add a new submodule.
Function	`submodule_init`	Initialize submodules.
Function	`submodule_list`	List submodules.
Function	`submodule_update`	Update submodules.
Function	`switch`	Switch branches.
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	`tree_path_to_fs_path`	Convert a git tree path to a filesystem path (relative).
Function	`unpack_objects`	Unpack objects from a pack file into the repository.
Function	`update_head`	Update HEAD to point at a new branch/commit.
Function	`update_ref`	Update the object name stored in a ref safely.
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	`var`	Get the value of a specific Git logical variable.
Function	`var_list`	List all Git logical variables.
Function	`verify_commit`	Verify signature on a commit.
Function	`verify_tag`	Verify signature on a tag.
Function	`web_daemon`	Run a daemon serving Git requests over HTTP.
Function	`worktree_add`	Add a new worktree.
Function	`worktree_list`	List all worktrees for a repository.
Function	`worktree_lock`	Lock a worktree to prevent it from being pruned.
Function	`worktree_move`	Move a worktree to a new location.
Function	`worktree_prune`	Prune worktree administrative files.
Function	`worktree_remove`	Remove a worktree.
Function	`worktree_repair`	Repair worktree administrative files.
Function	`worktree_unlock`	Unlock a worktree.
Function	`write_commit_graph`	Write a commit graph file for a repository.
Function	`write_tree`	Write a tree object from the index.
Constant	`DEFAULT_ENCODING`	Undocumented
Constant	`INFINITE_DEPTH`	Undocumented
Type Variable	`T`	Undocumented
Variable	`default_bytes_err_stream`	Undocumented
Variable	`default_bytes_out_stream`	Undocumented
Variable	`GitStatus`	Undocumented
Variable	`RepoPath`	Undocumented
Function	`_canonical_part`	Undocumented
Function	`_check_uncommitted_changes`	Check for uncommitted changes that would conflict with a checkout/switch.
Function	`_do_merge`	Internal merge implementation that operates on an open repository.
Function	`_do_octopus_merge`	Internal octopus merge implementation that operates on an open repository.
Function	`_filter_transport_kwargs`	Filter kwargs to only include parameters accepted by get_transport_and_path.
Function	`_find_reachable_tags`	Yield annotated tags whose targets are reachable from pushed commits.
Function	`_get_branch_merge_status`	Get merge status for all branches relative to current HEAD.
Function	`_get_current_head_tree`	Get the current HEAD tree ID.
Function	`_get_reflog_message`	Get reflog message, checking GIT_REFLOG_ACTION environment variable.
Function	`_get_variables`	Internal function to get all Git logical variables.
Function	`_get_worktree_update_config`	Get configuration for working tree updates.
Function	`_is_subdir`	Check whether subdir is parentdir or a subdir of parentdir.
Function	`_make_branch_ref`	Undocumented
Function	`_make_replace_ref`	Undocumented
Function	`_noop_context_manager`	Context manager that has the same api as closing but does nothing.
Function	`_perform_tree_switch`	Perform the actual working tree switch.
Function	`_precompose_unicode_path`	Normalize a filesystem path to NFC (precomposed) Unicode form.
Function	`_quote_path`	Quote a path using C-style quoting similar to git's core.quotePath.
Function	`_select_push_refs`	Select which refs to push based on mode flags or user refspecs.
Function	`_walk_working_dir_paths`	Get path, is_dir for files in working dir from frompath.

def active_branch(repo: RepoPath) -> bytes: ¶

Return the active branch in the repository, if any.

Parameters
repo:`RepoPath`	Repository to open

Returns
`bytes`	branch name

Raises
`KeyError`	if the repository does not have a working tree
`IndexError`	if HEAD is floating

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.

Note: When paths=None, this function adds all untracked and modified files from the entire repository, mimicking 'git add -A' behavior.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Repository for the files
paths:`Sequence[str \| bytes \| os.PathLike[str]] \| str \| bytes \| os.PathLike[str] \| None`	Paths to add. If None, stages all untracked and modified files from the current working directory (mimicking 'git add .' behavior).

Returns
`tuple[list[str], set[str]]`	Undocumented

Apply patches from mailbox-style email messages, creating commits.

Parameters
repo:`RepoPath`	Path to the repository
patches:`str \| bytes \| BinaryIO \| list[str \| bytes \| BinaryIO] \| None`	Patch input(s) - file path(s), file-like object(s), or None for stdin. Can be a single mbox file containing multiple messages.
three_way:`bool`	Fall back to 3-way merge if patch does not apply cleanly
keep_subject:`bool`	If True, keep subject intact without munging
keep_non_patch:`bool`	If True, only strip [PATCH] from brackets
scissors:`bool`	If True, remove everything before scissors line
message_id:`bool`	If True, include Message-ID in commit message
strip:`int`	Number of leading path components to strip (default: 1)
committer:`bytes \| None`	Optional committer identity (bytes)
commit_timestamp:`float \| None`	Optional committer timestamp
commit_timezone:`int \| None`	Optional committer timezone offset

Returns
`list[ObjectID]`	List of commit SHAs (bytes) created

def am_abort(repo: RepoPath = '.'): ¶

Abort the current am and restore the original state.

Resets HEAD, index, and working tree to the state before am started.

Parameters
repo:`RepoPath`	Path to the repository

def am_continue(repo: RepoPath = '.', committer: bytes | None = None, commit_timestamp: float | None = None, commit_timezone: int | None = None) -> list[ObjectID]: ¶

Continue applying patches after resolving a conflict.

The user should have resolved conflicts and staged the result.

Parameters
repo:`RepoPath`	Path to the repository
committer:`bytes \| None`	Optional committer identity
commit_timestamp:`float \| None`	Optional committer timestamp
commit_timezone:`int \| None`	Optional committer timezone offset

Returns
`list[ObjectID]`	List of commit SHAs created

def am_quit(repo: RepoPath = '.'): ¶

Quit the current am without reverting changes.

Removes am state but keeps HEAD, index, and working tree as-is.

Parameters
repo:`RepoPath`	Path to the repository

def am_skip(repo: RepoPath = '.', committer: bytes | None = None, commit_timestamp: float | None = None, commit_timezone: int | None = None) -> list[ObjectID]: ¶

Skip the current patch and continue with remaining patches.

Parameters
repo:`RepoPath`	Path to the repository
committer:`bytes \| None`	Optional committer identity
commit_timestamp:`float \| None`	Optional committer timestamp
commit_timezone:`int \| None`	Optional committer timezone offset

Returns
`list[ObjectID]`	List of commit SHAs created

Annotate the history of a file.

Parameters
repo:`RepoPath`	Path to the repository
path:`str \| bytes`	Path to annotate
committish:`str \| bytes \| Commit \| Tag \| None`	Commit id to find path in

Returns
`list[tuple[tuple[Commit, TreeEntry], bytes]]`	List of ((Commit, TreeChange), line) tuples

def apply_patch(repo: RepoPath = '.', patch_file: str | bytes | BinaryIO | None = None, cached: bool = False, reverse: bool = False, check: bool = False, strip: int = 1, three_way: bool = False): ¶

Apply a patch to the working tree and/or index.

Parameters
repo:`RepoPath`	Path to the repository
patch_file:`str \| bytes \| BinaryIO \| None`	Path to patch file or file-like object (stdin if None)
cached:`bool`	Apply patch to index only, not working tree
reverse:`bool`	Apply patch in reverse
check:`bool`	Only check if patch can be applied, don't apply
strip:`int`	Number of leading path components to strip (default: 1)
three_way:`bool`	Fall back to 3-way merge if patch does not apply cleanly

Raises
`ValueError`	If patch cannot be applied

Create an archive.

Parameters
repo:`str \| BaseRepo`	Path of repository for which to generate an archive.
committish:`str \| bytes \| Commit \| Tag \| None`	Commit SHA1 or ref to use
outstream:`BinaryIO \| RawIOBase`	Output stream (defaults to stdout)
errstream:`BinaryIO \| RawIOBase`	Error stream (defaults to stderr)

Mark a commit as bad.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to repository or a Repo object
rev:`str \| bytes \| Commit \| Tag \| None`	Commit to mark as bad (defaults to HEAD)

Returns
`bytes \| None`	The SHA of the next commit to test, or None if bisect is complete

Mark a commit as good.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to repository or a Repo object
rev:`str \| bytes \| Commit \| Tag \| None`	Commit to mark as good (defaults to HEAD)

Returns
`bytes \| None`	The SHA of the next commit to test, or None if bisect is complete

def bisect_log(repo: str | os.PathLike[str] | Repo = '.') -> str: ¶

Get the bisect log.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to repository or a Repo object

Returns
`str`	The bisect log as a string

def bisect_replay(repo: str | os.PathLike[str] | Repo, log_file: str | os.PathLike[str] | BinaryIO): ¶

Replay a bisect log.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to repository or a Repo object
log_file:`str \| os.PathLike[str] \| BinaryIO`	Path to the log file or file-like object

Reset bisect state and return to original branch/commit.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to repository or a Repo object
commit:`str \| bytes \| Commit \| Tag \| None`	Optional commit to reset to (defaults to original branch/commit)

Skip one or more commits.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to repository or a Repo object
revs:`str \| bytes \| Commit \| Tag \| Sequence[str \| bytes \| Commit \| Tag] \| None`	List of commits to skip (defaults to [HEAD])

Returns
`bytes \| None`	The SHA of the next commit to test, or None if bisect is complete

Start a new bisect session.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to repository or a Repo object
bad:`str \| bytes \| Commit \| Tag \| None`	The bad commit (defaults to HEAD)
good:`str \| bytes \| Commit \| Tag \| Sequence[str \| bytes \| Commit \| Tag] \| None`	List of good commits or a single good commit
paths:`Sequence[bytes] \| None`	Optional paths to limit bisect to
no_checkout:`bool`	If True, don't checkout commits during bisect
term_bad:`str`	Term to use for bad commits (default: "bad")
term_good:`str`	Term to use for good commits (default: "good")

Returns
`bytes \| None`	Undocumented

Create a branch.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to the repository
name:`str \| bytes`	Name of the new branch
objectish:`str \| bytes \| None`	Target object to point new branch at (defaults to HEAD)
force:`bool`	Force creation of branch, even if it already exists

def branch_delete(repo: RepoPath, name: str | bytes | Sequence[str | bytes]): ¶

Delete a branch.

Parameters
repo:`RepoPath`	Path to the repository
name:`str \| bytes \| Sequence[str \| bytes]`	Name of the branch

def branch_list(repo: RepoPath) -> list[Ref]: ¶

List all branches.

Parameters
repo:`RepoPath`	Path to the repository

Returns
`list[Ref]`	List of branch names (without refs/heads/ prefix)

def branch_remotes_list(repo: RepoPath) -> list[bytes]: ¶

List the short names of all remote branches.

Parameters
repo:`RepoPath`	Path to the repository

Returns
`list[bytes]`	List of branch names (without refs/remotes/ prefix, and without remote name; e.g. 'main' from 'origin/main')

def branches_containing(repo: RepoPath, commit: str) -> Iterator[bytes]: ¶

List branches that contain the specified commit.

Parameters
repo:`RepoPath`	Path to the repository
commit:`str`	Commit-ish string (SHA, branch name, tag, etc.)

Returns
`Iterator[bytes]`	Undocumented

Yields
Branch names (without refs/heads/ prefix) that contain the commit

Raises
`ValueError`	If the commit reference is malformed
`KeyError`	If the commit reference does not exist

def cat_file_content(repo: str | os.PathLike[str] | Repo, objectish: str | bytes) -> bytes: ¶

Get the raw content of a Git object.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to the repository or a Repo object
objectish:`str \| bytes`	Object SHA, reference, or objectish (e.g., 'HEAD', 'main', 'abc123')

Returns
`bytes`	Raw object content as bytes

def cat_file_size(repo: str | os.PathLike[str] | Repo, objectish: str | bytes) -> int: ¶

Get the size of a Git object.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to the repository or a Repo object
objectish:`str \| bytes`	Object SHA, reference, or objectish (e.g., 'HEAD', 'main', 'abc123')

Returns
`int`	Object size in bytes

def cat_file_type(repo: str | os.PathLike[str] | Repo, objectish: str | bytes) -> bytes: ¶

Get the type of a Git object.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to the repository or a Repo object
objectish:`str \| bytes`	Object SHA, reference, or objectish (e.g., 'HEAD', 'main', 'abc123')

Returns
`bytes`	Object type as bytes (b'blob', b'tree', b'commit', or b'tag')

def check_diverged(repo: BaseRepo, current_sha: ObjectID, new_sha: ObjectID): ¶

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

Parameters
repo:`BaseRepo`	Repository object
current_sha:`ObjectID`	Current head sha
new_sha:`ObjectID`	New head sha

def check_ignore(repo: RepoPath, paths: Sequence[str | bytes | os.PathLike[str]], no_index: bool = False, quote_path: bool = True) -> Iterator[str]: ¶

Debug gitignore files.

Returns: List of ignored files

Parameters
repo:`RepoPath`	Path to the repository
paths:`Sequence[str \| bytes \| os.PathLike[str]]`	List of paths to check for
no_index:`bool`	Don't check index
quote_path:`bool`	If True, quote non-ASCII characters in returned paths using C-style octal escapes (e.g. "тест.txt" becomes "\321\202\320\265\321\201\321\202.txt"). If False, return raw unicode paths.

Returns
`Iterator[str]`	Undocumented

def check_mailmap(repo: RepoPath, contact: str | bytes) -> bytes: ¶

Check canonical name and email of contact.

Returns: Canonical contact data

Parameters
repo:`RepoPath`	Path to the repository
contact:`str \| bytes`	Contact name and/or email

Returns
`bytes`	Undocumented

Switch to a branch or commit, updating both HEAD and the working tree.

This is similar to 'git checkout', allowing you to switch to a branch, tag, or specific commit. Unlike update_head, this function also updates the working tree to match the target.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to repository or repository object
target:`str \| bytes \| Commit \| Tag \| None`	Branch name, tag, or commit SHA to checkout. If None and paths is specified, restores files from HEAD
force:`bool`	Force checkout even if there are local changes
new_branch:`bytes \| str \| None`	Create a new branch at target (like git checkout -b)
paths:`list[bytes \| str] \| None`	List of specific paths to checkout. If specified, only these paths are updated and HEAD is not changed

Raises
`CheckoutError`	If checkout cannot be performed due to conflicts
`KeyError`	If the target reference cannot be found

Find commits not merged upstream.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Repository path or object
upstream:`str \| bytes \| None`	Upstream branch (default: tracking branch or @{upstream})
head:`str \| bytes \| None`	Head branch (default: HEAD)
limit:`str \| bytes \| None`	Limit commits to those after this ref
verbose:`bool`	Include commit messages in output

Returns
`list[tuple[str, bytes, bytes \| None]]`	List of tuples (status, commit_sha, message) where status is '+' or '-' '+' means commit is not in upstream, '-' means equivalent patch exists upstream message is None unless verbose=True

Cherry-pick a commit onto the current branch.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Repository to cherry-pick into
committish:`str \| bytes \| Commit \| Tag \| None`	Commit to cherry-pick (can be None only when resuming or aborting)
no_commit:`bool`	If True, do not create a commit after applying changes
continue_:`bool`	Resume an in-progress cherry-pick after resolving conflicts if True
abort:`bool`	Abort an in-progress cherry-pick

Returns
`bytes \| None`	The SHA of the newly created commit, or None if no_commit=True or there were conflicts

Raises
`Error`	If there is no HEAD reference, commit cannot be found, or operation fails

def clean(repo: str | os.PathLike[str] | Repo = '.', target_dir: str | os.PathLike[str] | None = None): ¶

Remove any untracked files from the target directory recursively.

Equivalent to running git clean -fd in target_dir.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Repository where the files may be tracked
target_dir:`str \| os.PathLike[str] \| None`	Directory to clean - current directory if None

Clone a local or remote git repository.

Returns: The new repository

Parameters
source:`str \| bytes \| Repo`	Path or URL for source repository
target:`str \| os.PathLike[str] \| None`	Path to target repository (optional)
bare:`bool`	Whether or not to create a bare repository
checkout:`bool \| None`	Whether or not to check-out HEAD after cloning
errstream:`BinaryIO \| RawIOBase`	Optional stream to write progress to
outstream:`BinaryIO \| None`	Optional stream to write progress to (deprecated)
origin:`str \| None`	Name of remote from the repository used to clone
depth:`int \| None`	Depth to fetch at
branch:`str \| bytes \| None`	Optional branch or tag to be used as HEAD in the new repository instead of the cloned repository's HEAD.
config:`Config \| None`	Configuration to use
filter_spec:`str \| None`	A git-rev-list-style object filter spec, as an ASCII string. Only used if the server supports the Git protocol-v2 'filter' feature, and ignored otherwise.
protocol_version:`int \| None`	desired Git protocol version. By default the highest mutually supported protocol version will be used.
recurse_submodules:`bool`	Whether to initialize and clone submodules
ssh_command:`str \| None`	Optional custom SSH command
**kwargs:`str \| bytes \| Sequence[str \| bytes]`	Additional keyword arguments including refspecs to fetch. Can be a bytestring, a string, or a list of bytestring/string.

Returns
`Repo`	Undocumented

Create a new commit.

Returns: SHA1 of the new commit

Parameters
repo:`RepoPath`	Path to repository
message:`str \| bytes \| Callable[[Any, Commit], bytes] \| None`	Optional commit message (string/bytes or callable that takes (repo, commit) and returns bytes)
author:`bytes \| None`	Optional author name and email
author_timestamp:`float \| None`	Author timestamp (defaults to commit timestamp)
author_timezone:`int \| None`	Author timestamp timezone
committer:`bytes \| None`	Optional committer name and email
commit_timestamp:`float \| None`	Commit timestamp (defaults to now)
commit_timezone:`int \| None`	Commit timestamp timezone
encoding:`bytes \| None`	Encoding to use for commit message
no_verify:`bool`	Skip pre-commit and commit-msg hooks
signoff:`bool \| None`	Add Signed-off-by line to commit message. If None, uses format.signoff config.
all:`bool`	Automatically stage all tracked files that have been modified
amend:`bool`	Replace the tip of the current branch by creating a new commit
sign:`bool \| None`	GPG sign the commit. If None, uses commit.gpgsign config. If True, signs with default GPG key. If False, does not sign.

Returns
`bytes`	Undocumented

def commit_decode(commit: Commit, contents: bytes, default_encoding: str = DEFAULT_ENCODING) -> str: ¶

Decode commit contents using the commit's encoding or default.

def commit_encode(commit: Commit, contents: str, default_encoding: str = DEFAULT_ENCODING) -> bytes: ¶

Encode commit contents using the commit's encoding or default.

def commit_tree(repo: RepoPath, tree: ObjectID, message: str | bytes | None = None, author: bytes | None = None, committer: bytes | None = None) -> ObjectID: ¶

Create a new commit object.

Parameters
repo:`RepoPath`	Path to repository
tree:`ObjectID`	An existing tree object
message:`str \| bytes \| None`	Commit message
author:`bytes \| None`	Optional author name and email
committer:`bytes \| None`	Optional committer name and email

Returns
`ObjectID`	Undocumented

def cone_mode_add(repo: str | os.PathLike[str] | Repo, dirs: Sequence[str], force: bool = False): ¶

Add new directories to the existing 'cone-mode' sparse-checkout patterns.

Reads the current patterns from .git/info/sparse-checkout, adds pattern lines to include the specified directories, and then performs a sparse checkout to update the working tree accordingly.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to the repository or a Repo object.
dirs:`Sequence[str]`	List of directory names to add to the sparse-checkout.
force:`bool`	Whether to forcibly discard local modifications (default False).

Returns
None

def cone_mode_disable(repo: str | os.PathLike[str] | Repo, force: bool = False): ¶

Disable sparse checkout and restore all files.

This function: 1. Unsets core.sparseCheckout and core.sparseCheckoutCone config 2. Removes the .git/info/sparse-checkout file 3. Restores all files to the working tree

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to the repository or a Repo object.
force:`bool`	Whether to forcibly discard local modifications (default False).

Returns
None

def cone_mode_init(repo: str | os.PathLike[str] | Repo): ¶

Initialize a repository to use sparse checkout in 'cone' mode.

Sets core.sparseCheckout and core.sparseCheckoutCone in the config. Writes an initial .git/info/sparse-checkout file that includes only top-level files (and excludes all subdirectories), e.g. ["/*", "!/*/"]. Then performs a sparse checkout to update the working tree accordingly.

If no directories are specified, then only top-level files are included: https://git-scm.com/docs/git-sparse-checkout#_internalscone_mode_handling

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to the repository or a Repo object.

Returns
None

def cone_mode_list(repo: str | os.PathLike[str] | Repo) -> list[str]: ¶

List current sparse-checkout patterns.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to the repository or a Repo object.

Returns
`list[str]`	List of sparse-checkout patterns

def cone_mode_set(repo: str | os.PathLike[str] | Repo, dirs: Sequence[str], force: bool = False): ¶

Overwrite the existing 'cone-mode' sparse patterns with a new set of directories.

Ensures core.sparseCheckout and core.sparseCheckoutCone are enabled. Writes new patterns so that only the specified directories (and top-level files) remain in the working tree, and applies the sparse checkout update.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to the repository or a Repo object.
dirs:`Sequence[str]`	List of directory names to include.
force:`bool`	Whether to forcibly discard local modifications (default False).

Returns
None

def count_objects(repo: RepoPath = '.', verbose: bool = False) -> CountObjectsResult: ¶

Count unpacked objects and their disk usage.

Parameters
repo:`RepoPath`	Path to repository or repository object
verbose:`bool`	Whether to return verbose information

Returns
`CountObjectsResult`	CountObjectsResult object with detailed statistics

def daemon(path: str | os.PathLike[str] = '.', address: str | None = None, port: int | None = None): ¶

Run a daemon serving Git requests over TCP/IP.

Parameters
path:`str \| os.PathLike[str]`	Path to the directory to serve.
address:`str \| None`	Optional address to listen on (defaults to ::)
port:`int \| None`	Optional port to listen on (defaults to TCP_GIT_PORT)

def describe(repo: str | os.PathLike[str] | Repo, abbrev: int | None = None) -> str: ¶

Describe the repository version.

Returns: a string description of the current git revision

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

Parameters
repo:`str \| os.PathLike[str] \| Repo`	git repository
abbrev:`int \| None`	number of characters of commit to take, default is 7

Returns
`str`	Undocumented

Show diff.

Parameters
repo:`RepoPath`	Path to repository
commit:`str \| bytes \| Commit \| None`	First commit to compare. If staged is True, compare index to this commit. If staged is False, compare working tree to this commit. If None, defaults to HEAD for staged and index for unstaged.
commit2:`str \| bytes \| Commit \| None`	Second commit to compare against first commit. If provided, show diff between commit and commit2 (ignoring staged flag).
staged:`bool`	If True, show staged changes (index vs commit). If False, show unstaged changes (working tree vs commit/index). Ignored if commit2 is provided.
paths:`Sequence[str \| bytes] \| None`	Optional list of paths to limit diff
outstream:`BinaryIO`	Stream to write to
diff_algorithm:`str \| None`	Algorithm to use for diffing ("myers" or "patience"), defaults to the underlying function's default if None

def diff_tree(repo: RepoPath, old_tree: str | bytes | Tree, new_tree: str | bytes | Tree, outstream: BinaryIO = default_bytes_out_stream): ¶

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

Parameters
repo:`RepoPath`	Path to repository
old_tree:`str \| bytes \| Tree`	Id of old tree
new_tree:`str \| bytes \| Tree`	Id of new tree
outstream:`BinaryIO`	Stream to write to

def fetch(repo: RepoPath, remote_location: str | bytes | None = None, outstream: TextIO = sys.stdout, errstream: BinaryIO | RawIOBase = default_bytes_err_stream, message: bytes | None = None, depth: int | None = None, prune: bool = False, prune_tags: bool = False, force: bool = False, operation: str | None = None, thin_packs: bool = True, report_activity: Callable[[int, str], None] | None = None, quiet: bool = False, include_tags: bool = False, username: str | None = None, password: str | None = None, key_filename: str | None = None, ssh_command: str | None = None, shallow_since: str | None = None, shallow_exclude: list[str] | None = None, unshallow: bool = False) -> FetchPackResult: ¶

Fetch objects from a remote server.

Parameters
repo:`RepoPath`	Path to the repository
remote_location:`str \| bytes \| None`	String identifying a remote server
outstream:`TextIO`	Output stream (defaults to stdout)
errstream:`BinaryIO \| RawIOBase`	Error stream (defaults to stderr)
message:`bytes \| None`	Reflog message (defaults to b"fetch: from <remote_name>")
depth:`int \| None`	Depth to fetch at
prune:`bool`	Prune remote removed refs
prune_tags:`bool`	Prune remote removed tags
force:`bool`	Force fetching even if it would overwrite local changes
operation:`str \| None`	Git operation for authentication (e.g., "fetch")
thin_packs:`bool`	Whether to use thin packs
report_activity:`Callable[[int, str], None] \| None`	Optional callback for reporting transport activity
quiet:`bool`	Whether to suppress progress output
include_tags:`bool`	Whether to include tags
username:`str \| None`	Username for authentication
password:`str \| None`	Password for authentication
key_filename:`str \| None`	SSH key filename
ssh_command:`str \| None`	SSH command to use
shallow_since:`str \| None`	Deepen or shorten the history to include commits after this date
shallow_exclude:`list[str] \| None`	Deepen or shorten the history to exclude commits reachable from these refs
unshallow:`bool`	Convert a shallow repository to a complete one

Returns
`FetchPackResult`	Dictionary with refs on the remote

Rewrite branch history by creating new commits with filtered properties.

This is similar to git filter-branch, allowing you to rewrite commit history by modifying trees, parents, author, committer, or commit messages.

Parameters
repo:`RepoPath`	Path to repository
branch:`str \| bytes`	Branch to rewrite (defaults to HEAD)
filter_fn:`Callable[[Commit], CommitData \| None] \| None`	Optional callable that takes a Commit object and returns a dict of updated fields (author, committer, message, etc.)
filter_author:`Callable[[bytes], bytes \| None] \| None`	Optional callable that takes author bytes and returns updated author bytes or None to keep unchanged
filter_committer:`Callable[[bytes], bytes \| None] \| None`	Optional callable that takes committer bytes and returns updated committer bytes or None to keep unchanged
filter_message:`Callable[[bytes], bytes \| None] \| None`	Optional callable that takes commit message bytes and returns updated message bytes
tree_filter:`Callable[[ObjectID, str], ObjectID \| None] \| None`	Optional callable that takes (tree_sha, temp_dir) and returns new tree SHA after modifying working directory
index_filter:`Callable[[ObjectID, str], ObjectID \| None] \| None`	Optional callable that takes (tree_sha, temp_index_path) and returns new tree SHA after modifying index
parent_filter:`Callable[[Sequence[ObjectID]], list[ObjectID]] \| None`	Optional callable that takes parent list and returns modified parent list
commit_filter:`Callable[[Commit, ObjectID], ObjectID \| None] \| None`	Optional callable that takes (Commit, tree_sha) and returns new commit SHA or None to skip commit
subdirectory_filter:`str \| bytes \| None`	Optional subdirectory path to extract as new root
prune_empty:`bool`	Whether to prune commits that become empty
tag_name_filter:`Callable[[bytes], bytes \| None] \| None`	Optional callable to rename tags
force:`bool`	Force operation even if branch has been filtered before
keep_original:`bool`	Keep original refs under refs/original/
refs:`list[bytes] \| None`	List of refs to rewrite (defaults to [branch])

Returns
`dict[ObjectID, ObjectID]`	Dict mapping old commit SHAs to new commit SHAs

Raises
`Error`	If branch is already filtered and force is False

def filter_branches_by_pattern(branches: Iterable[bytes], pattern: str) -> list[bytes]: ¶

Filter branches by fnmatch pattern.

Parameters
branches:`Iterable[bytes]`	Iterable of branch names as bytes
pattern:`str`	Pattern to match against

Returns
`list[bytes]`	List of filtered branch names

def find_unique_abbrev(object_store: BaseObjectStore, object_id: str | bytes, min_length: int = 7) -> str: ¶

Find the shortest unique abbreviation for an object ID.

Parameters
object_store:`BaseObjectStore`	Object store to search in
object_id:`str \| bytes`	The full object ID to abbreviate
min_length:`int`	Minimum length of abbreviation (default 7)

Returns
`str`	The shortest unique prefix of the object ID (at least min_length chars)

def for_each_ref(repo: Repo | str = '.', pattern: str | bytes | None = None) -> list[tuple[bytes, bytes, bytes]]: ¶

Iterate over all refs that match the (optional) pattern.

Returns: List of bytes tuples with: (sha, object_type, ref_name)

Parameters
repo:`Repo \| str`	Path to the repository
pattern:`str \| bytes \| None`	Optional glob (7) patterns to filter the refs with

Returns
`list[tuple[bytes, bytes, bytes]]`	Undocumented

def format_patch(repo: RepoPath = '.', committish: ObjectID | tuple[ObjectID, ObjectID] | None = None, outstream: TextIO = sys.stdout, outdir: str | os.PathLike[str] | None = None, n: int = 1, stdout: bool = False, version: str | None = None) -> list[str]: ¶

Generate patches suitable for git am.

Parameters
repo:`RepoPath`	Path to repository
committish:`ObjectID \| tuple[ObjectID, ObjectID] \| None`	Commit-ish or commit range to generate patches for. Can be a single commit id, or a tuple of (start, end) commit ids for a range. If None, formats the last n commits from HEAD.
outstream:`TextIO`	Stream to write to if stdout=True
outdir:`str \| os.PathLike[str] \| None`	Directory to write patch files to (default: current directory)
n:`int`	Number of patches to generate if committish is None
stdout:`bool`	Write patches to stdout instead of files
version:`str \| None`	Version string to include in patches (default: Dulwich version)

Returns
`list[str]`	List of patch filenames that were created (empty if stdout=True)

def fsck(repo: RepoPath) -> Iterator[tuple[bytes, Exception]]: ¶

Check a repository.

This function is shallow-aware and will not report errors for missing parent commits that are beyond the shallow boundary.

Returns: Iterator over errors/warnings

Parameters
repo:`RepoPath`	A path to the repository

Returns
`Iterator[tuple[bytes, Exception]]`	Undocumented

def gc(repo: RepoPath, auto: bool = False, aggressive: bool = False, prune: bool = True, grace_period: int | None = None, dry_run: bool = False, progress: Callable[[str], None] | None = None) -> GCStats: ¶

Run garbage collection on a repository.

Parameters
repo:`RepoPath`	Path to the repository or a Repo object
auto:`bool`	If True, only run gc if needed
aggressive:`bool`	If True, use more aggressive settings
prune:`bool`	If True, prune unreachable objects
grace_period:`int \| None`	Grace period in seconds for pruning. If None, reads gc.pruneExpire from config (default 2 weeks).
dry_run:`bool`	If True, only report what would be done
progress:`Callable[[str], None] \| None`	Optional progress callback

Returns
`GCStats`	GCStats object with garbage collection statistics

def get_branch_merge(repo: RepoPath, branch_name: bytes | None = None) -> bytes: ¶

Return the branch's merge reference (upstream branch), if any.

Parameters
repo:`RepoPath`	Repository to open
branch_name:`bytes \| None`	Name of the branch (defaults to active branch)

Returns
`bytes`	merge reference name (e.g. b"refs/heads/main")

Raises
`KeyError`	if the branch does not have a merge configuration

def get_branch_remote(repo: str | os.PathLike[str] | Repo) -> bytes: ¶

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

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Repository to open

Returns
`bytes`	remote name

Raises
`KeyError`	if the repository does not have a working tree

Get an object by path.

Returns: A ShaFile object

Parameters
repo:`RepoPath`	A path to the repository
path:`str \| bytes`	Path to look up
committish:`str \| bytes \| Commit \| Tag \| None`	Commit to look up path in

Returns
`Blob \| Tree \| Commit \| Tag`	Undocumented

def get_remote_repo(repo: Repo, remote_location: str | bytes | None = None) -> tuple[str | None, str]: ¶

Get the remote repository information.

Parameters
repo:`Repo`	Local repository object
remote_location:`str \| bytes \| None`	Optional remote name or URL; defaults to branch remote

Returns
`tuple[str \| None, str]`	Tuple of (remote_name, remote_url) where remote_name may be None if remote_location is a URL rather than a configured remote

def get_tree_changes(repo: RepoPath, index: Index | None = None) -> dict[str, list[str | bytes]]: ¶

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

Returns: dict with lists for each type of change

Parameters
repo:`RepoPath`	repo path or object
index:`Index \| None`	optional Index object to reuse (avoids re-opening the index)

Returns
`dict[str, list[str \| bytes]]`	Undocumented

def get_untracked_paths(frompath: str | bytes | os.PathLike[str], basepath: str | bytes | os.PathLike[str], index: Index, exclude_ignored: bool = False, untracked_files: str = 'all', precompose_unicode: bool = False) -> Iterator[str]: ¶

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:`str \| bytes \| os.PathLike[str]`	Path to walk
basepath:`str \| bytes \| os.PathLike[str]`	Path to compare to
index:`Index`	Index to check against
exclude_ignored:`bool`	Whether to exclude ignored paths
untracked_files:`str`	How to handle untracked files: - "no": return an empty list - "all": return all files in untracked directories - "normal": return untracked directories without listing their contents
precompose_unicode:`bool`	If True, normalize filesystem paths to NFC Unicode form. This is needed on macOS where the filesystem returns NFD paths.

Returns
`Iterator[str]`	Undocumented

def get_user_timezones() -> tuple[int, int]: ¶

Retrieve local timezone as described in git documentation.

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

Search for a pattern in tracked files.

Parameters
repo:`RepoPath`	Path to repository or Repo object
pattern:`str \| bytes`	Regular expression pattern to search for
outstream:`TextIO`	Stream to write results to
rev:`str \| bytes \| None`	Revision to search in (defaults to HEAD)
pathspecs:`Sequence[str \| bytes] \| None`	Optional list of path patterns to limit search
ignore_case:`bool`	Whether to perform case-insensitive matching
line_number:`bool`	Whether to output line numbers
max_depth:`int \| None`	Maximum directory depth to search
respect_ignores:`bool`	Whether to respect .gitignore patterns

Compute object ID and optionally write to object store.

Parameters
repo:`str \| os.PathLike[str] \| Repo \| None`	Path to the repository or a Repo object (required if write=True)
path:`str \| os.PathLike[str] \| None`	Path to file to hash (mutually exclusive with data)
data:`bytes \| None`	Data to hash (mutually exclusive with path)
object_type:`bytes`	Type of object (default: b'blob')
write:`bool`	Whether to write the object to the object store (default: False)

Returns
`bytes`	Object SHA as bytes

Raises
`ValueError`	If neither path nor data is provided, or both are provided
`ValueError`	If write=True but repo is None

def independent_commits(repo: RepoPath = '.', committishes: Sequence[str | bytes] | None = None) -> list[ObjectID]: ¶

Filter commits to only those that are not reachable from others.

Parameters
repo:`RepoPath`	Path to repository
committishes:`Sequence[str \| bytes] \| None`	List of commit references to filter

Returns
`list[ObjectID]`	List of commit IDs that are not ancestors of any other commits in the list

def init(path: str | os.PathLike[str] = '.', *, bare: bool = False, symlinks: bool | None = None, object_format: str | None = None) -> Repo: ¶

Create a new git repository.

Returns: A Repo instance

Parameters
path:`str \| os.PathLike[str]`	Path to repository.
bare:`bool`	Whether to create a bare repository.
symlinks:`bool \| None`	Whether to create actual symlinks (defaults to autodetect)
object_format:`str \| None`	Object format to use ("sha1" or "sha256", defaults to "sha1")

Returns
`Repo`	Undocumented

def interpret_trailers(message: str | bytes, *, trailers: list[tuple[str, str]] | None = None, trim_empty: bool = False, only_trailers: bool = False, only_input: bool = False, unfold: bool = False, parse: bool = False, where: str = 'end', if_exists: str = 'addIfDifferentNeighbor', if_missing: str = 'add', separators: str = ':') -> bytes: ¶

Parse and manipulate trailers in a commit message.

This function implements the functionality of git interpret-trailers, allowing parsing and manipulation of structured metadata (trailers) in commit messages.

Trailers are key-value pairs at the end of commit messages, formatted like:: Signed-off-by: Alice <[email protected]> Reviewed-by: Bob <[email protected]>

Examples

>>> msg = b"Subject\\n\\nBody text\\n"
>>> interpret_trailers(msg, trailers=[("Signed-off-by", "Alice <[email protected]>")])
b'Subject\\n\\nBody text\\n\\nSigned-off-by: Alice <[email protected]>\\n'

>>> msg = b"Subject\\n\\nSigned-off-by: Alice\\n"
>>> interpret_trailers(msg, only_trailers=True)
b'Signed-off-by: Alice\\n'

Parameters
message:`str \| bytes`	The commit message (string or bytes)
trailers:`list[tuple[str, str]] \| None`	List of (key, value) tuples to add as new trailers
trim_empty:`bool`	Remove trailers with empty values
only_trailers:`bool`	Output only the trailers, not the message body
only_input:`bool`	Don't add new trailers, only parse existing ones
unfold:`bool`	Join multiline trailer values into a single line
parse:`bool`	Shorthand for --only-trailers --only-input --unfold
where:`str`	Where to add new trailers ('end', 'start', 'after', 'before')
if_exists:`str`	How to handle duplicate keys - 'add': Always add - 'replace': Replace all existing - 'addIfDifferent': Add only if value differs from all existing - 'addIfDifferentNeighbor': Add only if value differs from neighbors - 'doNothing': Don't add if key exists
if_missing:`str`	What to do if key doesn't exist ('add' or 'doNothing')
separators:`str`	Valid separator characters (default ':')

Returns
`bytes`	The processed message as bytes

def is_ancestor(repo: RepoPath = '.', ancestor: str | bytes | None = None, descendant: str | bytes | None = None) -> bool: ¶

Check if one commit is an ancestor of another.

Parameters
repo:`RepoPath`	Path to repository
ancestor:`str \| bytes \| None`	Commit that might be the ancestor
descendant:`str \| bytes \| None`	Commit that might be the descendant

Returns
`bool`	True if ancestor is an ancestor of descendant, False otherwise

def is_interactive_rebase(repo: Repo | str) -> bool: ¶

Check if an interactive rebase is in progress.

Parameters
repo:`Repo \| str`	Repository to check

Returns
`bool`	True if interactive rebase is in progress, False otherwise

def lfs_clean(repo: str | os.PathLike[str] | Repo = '.', path: str | os.PathLike[str] | None = None) -> bytes: ¶

Clean a file by converting it to an LFS pointer.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to repository
path:`str \| os.PathLike[str] \| None`	Path to file to clean (relative to repo root)

Returns
`bytes`	LFS pointer content as bytes

def lfs_fetch(repo: str | os.PathLike[str] | Repo = '.', remote: str = 'origin', refs: list[str | bytes] | None = None) -> int: ¶

Fetch LFS objects from remote.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to repository
remote:`str`	Remote name (default: origin)
refs:`list[str \| bytes] \| None`	Specific refs to fetch LFS objects for (default: all refs)

Returns
`int`	Number of objects fetched

def lfs_init(repo: str | os.PathLike[str] | Repo = '.'): ¶

Initialize Git LFS in a repository.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to repository

Returns
None

def lfs_ls_files(repo: str | os.PathLike[str] | Repo = '.', ref: str | bytes | None = None) -> list[tuple[bytes, str, int]]: ¶

List files tracked by Git LFS.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to repository
ref:`str \| bytes \| None`	Git ref to check (defaults to HEAD)

Returns
`list[tuple[bytes, str, int]]`	List of (path, oid, size) tuples for LFS files

def lfs_migrate(repo: str | os.PathLike[str] | Repo = '.', include: list[str] | None = None, exclude: list[str] | None = None, everything: bool = False) -> int: ¶

Migrate files to Git LFS.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to repository
include:`list[str] \| None`	Patterns of files to include
exclude:`list[str] \| None`	Patterns of files to exclude
everything:`bool`	Migrate all files above a certain size

Returns
`int`	Number of migrated files

def lfs_pointer_check(repo: str | os.PathLike[str] | Repo = '.', paths: Sequence[str] | None = None) -> dict[str, Any | None]: ¶

Check if files are valid LFS pointers.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to repository
paths:`Sequence[str] \| None`	List of file paths to check (if None, check all files)

Returns
`dict[str, Any \| None]`	Dict mapping paths to LFSPointer objects (or None if not a pointer)

def lfs_pull(repo: str | os.PathLike[str] | Repo = '.', remote: str = 'origin') -> int: ¶

Pull LFS objects for current checkout.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to repository
remote:`str`	Remote name (default: origin)

Returns
`int`	Number of objects fetched

def lfs_push(repo: str | os.PathLike[str] | Repo = '.', remote: str = 'origin', refs: list[str | bytes] | None = None) -> int: ¶

Push LFS objects to remote.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to repository
remote:`str`	Remote name (default: origin)
refs:`list[str \| bytes] \| None`	Specific refs to push LFS objects for (default: current branch)

Returns
`int`	Number of objects pushed

def lfs_smudge(repo: str | os.PathLike[str] | Repo = '.', pointer_content: bytes | None = None) -> bytes: ¶

Smudge an LFS pointer by retrieving the actual content.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to repository
pointer_content:`bytes \| None`	LFS pointer content as bytes

Returns
`bytes`	Actual file content as bytes

def lfs_status(repo: str | os.PathLike[str] | Repo = '.') -> dict[str, list[str]]: ¶

Show status of LFS files.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to repository

Returns
`dict[str, list[str]]`	Dict with status information

def lfs_track(repo: str | os.PathLike[str] | Repo = '.', patterns: Sequence[str] | None = None) -> list[str]: ¶

Track file patterns with Git LFS.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to repository
patterns:`Sequence[str] \| None`	List of file patterns to track (e.g., [".bin", ".pdf"]) If None, returns current tracked patterns

Returns
`list[str]`	List of tracked patterns

def lfs_untrack(repo: str | os.PathLike[str] | Repo = '.', patterns: Sequence[str] | None = None) -> list[str]: ¶

Untrack file patterns from Git LFS.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to repository
patterns:`Sequence[str] \| None`	List of file patterns to untrack

Returns
`list[str]`	List of remaining tracked patterns

def log(repo: RepoPath = '.', paths: Sequence[str | bytes] | None = None, outstream: TextIO = sys.stdout, max_entries: int | None = None, reverse: bool = False, name_status: bool = False, name_only: bool = False, author: str | None = None, committer: str | None = None, grep: str | None = None, since: str | int | None = None, until: str | int | None = None, no_merges: bool = False, merges: bool = False, oneline: bool = False, abbrev_commit: bool = False, stat: bool = False, patch: bool = False, follow: bool = False): ¶

Write commit logs.

Parameters
repo:`RepoPath`	Path to repository
paths:`Sequence[str \| bytes] \| None`	Optional set of specific paths to print entries for
outstream:`TextIO`	Stream to write log output to
max_entries:`int \| None`	Optional maximum number of entries to display
reverse:`bool`	Reverse order in which entries are printed
name_status:`bool`	Print name/status for each changed file
name_only:`bool`	Print only names of changed files
author:`str \| None`	Filter commits by author pattern
committer:`str \| None`	Filter commits by committer pattern
grep:`str \| None`	Filter commits by message pattern
since:`str \| int \| None`	Show commits after this date (timestamp or date string)
until:`str \| int \| None`	Show commits before this date (timestamp or date string)
no_merges:`bool`	Exclude merge commits
merges:`bool`	Only show merge commits
oneline:`bool`	Show each commit on a single line
abbrev_commit:`bool`	Abbreviate commit hashes
stat:`bool`	Show diffstat for each commit
patch:`bool`	Show patch (diff) for each commit
follow:`bool`	Follow file renames

def ls_files(repo: RepoPath) -> list[bytes]: ¶

List all files in an index.

def ls_remote(remote: str | bytes, config: Config | None = None, operation: str | None = None, thin_packs: bool = True, report_activity: Callable[[int, str], None] | None = None, quiet: bool = False, include_tags: bool = False, username: str | None = None, password: str | None = None, key_filename: str | None = None, ssh_command: str | None = None) -> LsRemoteResult: ¶

List the refs in a remote.

Parameters
remote:`str \| bytes`	Remote repository location
config:`Config \| None`	Configuration to use
operation:`str \| None`	Operation type
thin_packs:`bool`	Whether to use thin packs
report_activity:`Callable[[int, str], None] \| None`	Function to report activity
quiet:`bool`	Whether to suppress output
include_tags:`bool`	Whether to include tags
username:`str \| None`	Username for authentication
password:`str \| None`	Password for authentication
key_filename:`str \| None`	SSH key filename
ssh_command:`str \| None`	SSH command to use

Returns
`LsRemoteResult`	LsRemoteResult object with refs and symrefs

List contents of a tree.

Parameters
repo:`RepoPath`	Path to the repository
treeish:`str \| bytes \| Commit \| Tree \| Tag`	Tree id to list
outstream:`TextIO \| BinaryIO`	Output stream (defaults to stdout)
recursive:`bool`	Whether to recursively list files
name_only:`bool`	Only print item name

Extract patch information from an email message.

This is similar to git mailinfo.

Example

>>> result = mailinfo("patch.eml", "msg", "patch")
>>> print(f"Author: {result.author_name} <{result.author_email}>")
>>> print(f"Subject: {result.subject}")

Parameters
input_path:`str \| os.PathLike[str] \| IO[bytes] \| IO[str] \| None`	Path to email file or file-like object. If None, reads from stdin.
msg_file:`str \| os.PathLike[str] \| None`	Path to write commit message. If None, message not written to file.
patch_file:`str \| os.PathLike[str] \| None`	Path to write patch content. If None, patch not written to file.
keep_subject:`bool`	If True, keep subject intact without munging (-k)
keep_non_patch:`bool`	If True, only strip [PATCH] from brackets (-b)
encoding:`str \| None`	Character encoding to use (default: detect from message)
scissors:`bool`	If True, remove everything before scissors line
message_id:`bool`	If True, include Message-ID in commit message (-m)

Returns
`MailinfoResult`	MailinfoResult with parsed information

Raises
`ValueError`	If message is malformed or missing required fields
`OSError`	If there are issues reading/writing files

def mailsplit(input_path: str | os.PathLike[str] | IO[bytes] | None = None, output_dir: str | os.PathLike[str] = '.', start_number: int = 1, precision: int = 4, keep_cr: bool = False, mboxrd: bool = False, is_maildir: bool = False) -> list[str]: ¶

Split an mbox file or Maildir into individual message files.

This is similar to git mailsplit.

Parameters
input_path:`str \| os.PathLike[str] \| IO[bytes] \| None`	Path to mbox file, Maildir, or file-like object. If None, reads from stdin.
output_dir:`str \| os.PathLike[str]`	Directory where individual messages will be written
start_number:`int`	Starting number for output files (default: 1)
precision:`int`	Number of digits for output filenames (default: 4)
keep_cr:`bool`	If True, preserve r in lines ending with rn (default: False)
mboxrd:`bool`	If True, treat input as mboxrd format and reverse escaping (default: False)
is_maildir:`bool`	If True, treat input_path as a Maildir (default: False)

Returns
`list[str]`	List of output file paths that were created

Raises
`ValueError`	If output_dir doesn't exist or input is invalid
`OSError`	If there are issues reading/writing files

def maintenance_register(repo: RepoPath): ¶

This adds the repository to the global maintenance.repo config and sets up recommended configuration for scheduled maintenance.

Parameters
repo:`RepoPath`	Path to the repository or repository object

def maintenance_run(repo: RepoPath, tasks: list[str] | None = None, auto: bool = False, progress: Callable[[str], None] | None = None) -> MaintenanceResult: ¶

Run maintenance tasks on a repository.

Parameters
repo:`RepoPath`	Path to the repository or a Repo object
tasks:`list[str] \| None`	Optional list of specific task names to run (e.g., ['gc', 'commit-graph', 'pack-refs'])
auto:`bool`	If True, only run tasks if needed
progress:`Callable[[str], None] \| None`	Optional progress callback

Returns
`MaintenanceResult`	MaintenanceResult object with task execution results

def maintenance_unregister(repo: RepoPath, force: bool = False): ¶

Unregister a repository from background maintenance.

This removes the repository from the global maintenance.repo config.

Parameters
repo:`RepoPath`	Path to the repository or repository object
force:`bool`	If True, don't error if repository is not registered

Merge one or more commits into the current branch.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Repository to merge into
committish:`str \| bytes \| Commit \| Tag \| Sequence[str \| bytes \| Commit \| Tag]`	Commit(s) to merge. Can be a single commit or a sequence of commits. When merging more than two heads, the octopus merge strategy is used.
no_commit:`bool`	If True, do not create a merge commit
no_ff:`bool`	If True, force creation of a merge commit
message:`bytes \| None`	Optional merge commit message
author:`bytes \| None`	Optional author for merge commit
committer:`bytes \| None`	Optional committer for merge commit

Returns
`tuple[bytes \| None, list[bytes]]`	Tuple of (merge_commit_sha, conflicts) where merge_commit_sha is None if no_commit=True or there were conflicts

Raises
`Error`	If there is no HEAD reference or commit cannot be found

def merge_base(repo: RepoPath = '.', committishes: Sequence[str | bytes] | None = None, all: bool = False, octopus: bool = False) -> list[ObjectID]: ¶

Find the best common ancestor(s) between commits.

Parameters
repo:`RepoPath`	Path to repository
committishes:`Sequence[str \| bytes] \| None`	List of commit references (branches, tags, commit IDs)
all:`bool`	If True, return all merge bases, not just one
octopus:`bool`	If True, find merge base of all commits (n-way merge)

Returns
`list[ObjectID]`	List of commit IDs that are merge bases

Perform a three-way tree merge without touching the working directory.

This is similar to git merge-tree, performing a merge at the tree level without creating commits or updating any references.

Parameters
repo:`RepoPath`	Repository containing the trees
base_tree:`str \| bytes \| Tree \| Commit \| Tag \| None`	Tree-ish of the common ancestor (or None for no common ancestor)
our_tree:`str \| bytes \| Tree \| Commit \| Tag`	Tree-ish of our side of the merge
their_tree:`str \| bytes \| Tree \| Commit \| Tag`	Tree-ish of their side of the merge

Returns
`tuple`	A tuple of (merged_tree_id, conflicts) where: merged_tree_id is the SHA-1 of the merged tree conflicts is a list of paths (as bytes) that had conflicts

Raises
`KeyError`	If any of the tree-ish arguments cannot be resolved

def merged_branches(repo: RepoPath) -> Iterator[bytes]: ¶

List branches that have been merged into the current branch.

Parameters
repo:`RepoPath`	Path to the repository

Returns
`Iterator[bytes]`	Undocumented

Yields
Branch names (without refs/heads/ prefix) that are merged into the current HEAD

def mktag(repo: str | os.PathLike[str] | Repo, tag_data: bytes) -> bytes: ¶

Create a tag object from raw tag data.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to the repository or a Repo object
tag_data:`bytes`	Raw tag data in git tag format

Returns
`bytes`	Object SHA of the created tag as bytes

Raises
`ObjectFormatException`	If the tag data is invalid

Move or rename a file, directory, or symlink.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to the repository
source:`str \| bytes \| os.PathLike[str]`	Path to move from
destination:`str \| bytes \| os.PathLike[str]`	Path to move to
force:`bool`	Force move even if destination exists

Raises
`Error`	If source doesn't exist, is not tracked, or destination already exists (without force)

def no_merged_branches(repo: RepoPath) -> Iterator[bytes]: ¶

List branches that have been merged into the current branch.

Parameters
repo:`RepoPath`	Path to the repository

Returns
`Iterator[bytes]`	Undocumented

Yields
Branch names (without refs/heads/ prefix) that are merged into the current HEAD

def notes_add(repo: RepoPath, object_sha: bytes, note: bytes, ref: bytes = b'commits', author: bytes | None = None, committer: bytes | None = None, message: bytes | None = None) -> bytes: ¶

Add or update a note for an object.

Parameters
repo:`RepoPath`	Path to repository
object_sha:`bytes`	SHA of the object to annotate
note:`bytes`	Note content
ref:`bytes`	Notes ref to use (defaults to "commits" for refs/notes/commits)
author:`bytes \| None`	Author identity (defaults to committer)
committer:`bytes \| None`	Committer identity (defaults to config)
message:`bytes \| None`	Commit message for the notes update

Returns
`bytes`	SHA of the new notes commit

def notes_list(repo: RepoPath, ref: bytes = b'commits') -> list[tuple[ObjectID, bytes]]: ¶

List all notes in a notes ref.

Parameters
repo:`RepoPath`	Path to repository
ref:`bytes`	Notes ref to use (defaults to "commits" for refs/notes/commits)

Returns
`list[tuple[ObjectID, bytes]]`	List of tuples of (object_sha, note_content)

def notes_remove(repo: RepoPath, object_sha: bytes, ref: bytes = b'commits', author: bytes | None = None, committer: bytes | None = None, message: bytes | None = None) -> bytes | None: ¶

Remove a note for an object.

Parameters
repo:`RepoPath`	Path to repository
object_sha:`bytes`	SHA of the object to remove notes from
ref:`bytes`	Notes ref to use (defaults to "commits" for refs/notes/commits)
author:`bytes \| None`	Author identity (defaults to committer)
committer:`bytes \| None`	Committer identity (defaults to config)
message:`bytes \| None`	Commit message for the notes removal

Returns
`bytes \| None`	SHA of the new notes commit, or None if no note existed

def notes_show(repo: RepoPath, object_sha: bytes, ref: bytes = b'commits') -> bytes | None: ¶

Show the note for an object.

Parameters
repo:`RepoPath`	Path to repository
object_sha:`bytes`	SHA of the object
ref:`bytes`	Notes ref to use (defaults to "commits" for refs/notes/commits)

Returns
`bytes \| None`	Note content as bytes, or None if no note exists

@overload

def open_repo(path_or_repo: T) -> AbstractContextManager[T]:

@overload

def open_repo(path_or_repo: str | os.PathLike[str]) -> AbstractContextManager[Repo]:

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

@overload

def open_repo_closing(path_or_repo: T) -> AbstractContextManager[T]:

@overload

def open_repo_closing(path_or_repo: str | bytes | os.PathLike[str]) -> AbstractContextManager[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: RepoPath, object_ids: Sequence[ObjectID], packf: BinaryIO, idxf: BinaryIO | None, delta_window_size: int | None = None, deltify: bool | None = None, reuse_deltas: bool = True, pack_index_version: int | None = None): ¶

Pack objects into a file.

Parameters
repo:`RepoPath`	Path to the repository
object_ids:`Sequence[ObjectID]`	List of object ids to write
packf:`BinaryIO`	File-like object to write to
idxf:`BinaryIO \| None`	File-like object to write to (can be None)
delta_window_size:`int \| None`	Sliding window size for searching for deltas; Set to None for default window size.
deltify:`bool \| None`	Whether to deltify objects
reuse_deltas:`bool`	Allow reuse of existing deltas while deltifying
pack_index_version:`int \| None`	Pack index version to use (1, 2, or 3). If None, uses default version.

def pack_refs(repo: RepoPath, all: bool = False): ¶

Pack loose references into packed-refs file.

def parse_timezone_format(tz_str: str) -> int: ¶

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:`str`	datetime string

Returns
`int`	Undocumented

Raises
`TimezoneFormatError`	if timezone information cannot be extracted

def path_to_tree_path(repopath: str | bytes | os.PathLike[str], path: str | bytes | os.PathLike[str], tree_encoding: str = DEFAULT_ENCODING) -> bytes: ¶

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:`str \| bytes \| os.PathLike[str]`	Repository path, absolute or relative to the cwd
path:`str \| bytes \| os.PathLike[str]`	A path, absolute or relative to the cwd
tree_encoding:`str`	Encoding to use for tree paths

Returns
`bytes`	Undocumented

def print_commit(commit: Commit, decode: Callable[[bytes], str], outstream: TextIO = sys.stdout, abbrev_commit: bool = False): ¶

Write a human-readable commit log entry.

Parameters
commit:`Commit`	A `Commit` object
decode:`Callable[[bytes], str]`	Function to decode commit data
outstream:`TextIO`	A stream file to write to
abbrev_commit:`bool`	If True, abbreviate commit hashes

def print_name_only(changes: Iterator[TreeChange]) -> Iterator[str]: ¶

Print only the names of changed files.

Parameters
changes:`Iterator[TreeChange]`	Iterator of TreeChange objects

Returns
`Iterator[str]`	Undocumented

Yields
Formatted name-only strings for each change

def print_name_status(changes: Iterator[TreeChange]) -> Iterator[str]: ¶

Print a simple status summary, listing changed files.

def print_oneline(commit: Commit, decode: Callable[[bytes], str], outstream: TextIO = sys.stdout, abbrev_commit: bool = True): ¶

Write a single-line commit log entry.

Parameters
commit:`Commit`	A `Commit` object
decode:`Callable[[bytes], str]`	Function to decode commit data
outstream:`TextIO`	A stream file to write to
abbrev_commit:`bool`	If True, abbreviate commit hashes

def print_stat(store: BaseObjectStore, commit: Commit, outstream: TextIO = sys.stdout): ¶

Write a diffstat summary for a commit.

Parameters
store:`BaseObjectStore`	ObjectStore for looking up objects
commit:`Commit`	A `Commit` object
outstream:`TextIO`	A stream file to write to

def print_tag(tag: Tag, decode: Callable[[bytes], str], outstream: TextIO = sys.stdout): ¶

Write a human-readable tag.

Parameters
tag:`Tag`	A `Tag` object
decode:`Callable[[bytes], str]`	Function for decoding bytes to unicode string
outstream:`TextIO`	A stream to write to

def prune(repo: RepoPath, grace_period: int | None = None, dry_run: bool = False, progress: Callable[[str], None] | None = None): ¶

Prune/clean up a repository's object store.

This removes temporary files that were left behind by interrupted pack operations.

Parameters
repo:`RepoPath`	Path to the repository or a Repo object
grace_period:`int \| None`	Grace period in seconds for removing temporary files (default 2 weeks)
dry_run:`bool`	If True, only report what would be done
progress:`Callable[[str], None] \| None`	Optional progress callback

Pull from remote via dulwich.client.

Parameters
repo:`RepoPath`	Path to repository
remote_location:`str \| bytes \| None`	Location of the remote
refspecs:`str \| bytes \| Sequence[str \| bytes] \| None`	refspecs to fetch. Can be a bytestring, a string, or a list of bytestring/string.
outstream:`BinaryIO`	A stream file to write to output
errstream:`BinaryIO \| RawIOBase`	A stream file to write to errors
fast_forward:`bool`	If True, raise an exception when fast-forward is not possible
ff_only:`bool`	If True, only allow fast-forward merges. Raises DivergedBranches when branches have diverged rather than performing a merge.
force:`bool`	If True, allow overwriting local changes in the working tree. If False, pull will abort if it would overwrite uncommitted changes.
filter_spec:`str \| None`	A git-rev-list-style object filter spec, as an ASCII string. Only used if the server supports the Git protocol-v2 'filter' feature, and ignored otherwise.
protocol_version:`int \| None`	desired Git protocol version. By default the highest mutually supported protocol version will be used
**kwargs:`object`	Additional keyword arguments for the client

def push(repo: RepoPath, remote_location: str | bytes | None = None, refspecs: str | bytes | Sequence[str | bytes] | None = None, outstream: BinaryIO = default_bytes_out_stream, errstream: BinaryIO | RawIOBase = default_bytes_err_stream, force: bool = False, push_options: list[str] | None = None, atomic: bool = False, all: bool = False, tags: bool = False, delete: bool = False, dry_run: bool = False, prune: bool = False, set_upstream: bool = False, follow_tags: bool = False, mirror: bool = False, **kwargs: object) -> SendPackResult: ¶

Remote push with dulwich via dulwich.client.

Parameters
repo:`RepoPath`	Path to repository
remote_location:`str \| bytes \| None`	Location of the remote
refspecs:`str \| bytes \| Sequence[str \| bytes] \| None`	Refs to push to remote
outstream:`BinaryIO`	A stream file to write output
errstream:`BinaryIO \| RawIOBase`	A stream file to write errors
force:`bool`	Force overwriting refs
push_options:`list[str] \| None`	Optional list of push options to send to the server (e.g. for AGit flow: ["topic=my-branch", "title=My PR"])
atomic:`bool`	If True, request atomic push (all refs update or none do)
all:`bool`	If True, push all branches
tags:`bool`	If True, push all tags
delete:`bool`	If True, delete the specified remote refs
dry_run:`bool`	If True, do everything except actually send the updates
prune:`bool`	If True, remove remote refs that don't exist locally
set_upstream:`bool`	If True, set upstream tracking info for pushed branches
follow_tags:`bool`	If True, push annotated tags reachable from pushed commits
mirror:`bool`	If True, mirror all refs (implies force, push all refs and delete remote refs not present locally)
**kwargs:`object`	Additional keyword arguments for the client

Returns
`SendPackResult`	Undocumented

Rebase commits onto another branch.

Parameters
repo:`Repo \| str`	Repository to rebase in
upstream:`bytes \| str`	Upstream branch/commit to rebase onto
onto:`bytes \| str \| None`	Specific commit to rebase onto (defaults to upstream)
branch:`bytes \| str \| None`	Branch to rebase (defaults to current branch)
abort:`bool`	Abort an in-progress rebase
continue_rebase:`bool`	Continue an in-progress rebase
skip:`bool`	Skip current commit and continue rebase
interactive:`bool`	Start an interactive rebase
edit_todo:`bool`	Edit the todo list of an interactive rebase

Returns
`list[bytes]`	List of new commit SHAs created by rebase

Raises
`Error`	If rebase fails or conflicts occur

def receive_pack(path: str | os.PathLike[str] = '.', inf: BinaryIO | None = None, outf: BinaryIO | None = None) -> int: ¶

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

Parameters
path:`str \| os.PathLike[str]`	Path to the repository
inf:`BinaryIO \| None`	Input stream to communicate with client
outf:`BinaryIO \| None`	Output stream to communicate with client

Returns
`int`	Undocumented

def reflog(repo: RepoPath = '.', ref: str | bytes = b'HEAD', all: bool = False) -> Iterator[Any | tuple[bytes, Any]]: ¶

Show reflog entries for a reference or all references.

Parameters
repo:`RepoPath`	Path to repository or a Repo object
ref:`str \| bytes`	Reference name (defaults to HEAD)
all:`bool`	If True, show reflogs for all refs (ignores ref parameter)

Returns
`Iterator[Any \| tuple[bytes, Any]]`	Undocumented

Yields
`If all=False`	ReflogEntry objects If all=True: Tuples of (ref_name, ReflogEntry) for all refs with reflogs

def reflog_delete(repo: RepoPath = '.', ref: str | bytes = b'HEAD', index: int = 0, rewrite: bool = False): ¶

Delete a specific reflog entry.

Parameters
repo:`RepoPath`	Path to repository or a Repo object
ref:`str \| bytes`	Reference name
index:`int`	Reflog entry index (0 = newest, in Git reflog order)
rewrite:`bool`	If True, rewrite old_sha of subsequent entries to maintain consistency

def reflog_expire(repo: RepoPath = '.', ref: str | bytes | None = None, all: bool = False, expire_time: int | None = None, expire_unreachable_time: int | None = None, dry_run: bool = False) -> dict[bytes, int]: ¶

Expire reflog entries based on age and reachability.

Parameters
repo:`RepoPath`	Path to repository or a Repo object
ref:`str \| bytes \| None`	Reference name (if not using --all)
all:`bool`	If True, expire reflogs for all refs
expire_time:`int \| None`	Expire entries older than this timestamp (seconds since epoch)
expire_unreachable_time:`int \| None`	Expire unreachable entries older than this timestamp
dry_run:`bool`	If True, show what would be expired without making changes

Returns
`dict[bytes, int]`	Dictionary mapping ref names to number of expired entries

def remote_add(repo: RepoPath, name: bytes | str, url: bytes | str): ¶

Add a remote.

Parameters
repo:`RepoPath`	Path to the repository
name:`bytes \| str`	Remote name
url:`bytes \| str`	Remote URL

def remote_remove(repo: Repo, name: bytes | str): ¶

Remove a remote.

Parameters
repo:`Repo`	Path to the repository
name:`bytes \| str`	Remote name

def remove(repo: str | os.PathLike[str] | Repo = '.', paths: Sequence[str | bytes | os.PathLike[str]] = [], cached: bool = False): ¶

Remove files from the staging area.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Repository for the files
paths:`Sequence[str \| bytes \| os.PathLike[str]]`	Paths to remove. Can be absolute or relative to the repository root.
cached:`bool`	Only remove from index, not from working directory

def repack(repo: RepoPath, write_bitmaps: bool = False): ¶

Repack loose files in a repository.

Currently this only packs loose objects.

Parameters
repo:`RepoPath`	Path to the repository
write_bitmaps:`bool`	Whether to write bitmap indexes for packs

def replace_create(repo: RepoPath, object_sha: str | ObjectID, replacement_sha: str | ObjectID): ¶

Create a replacement ref to replace one object with another.

Parameters
repo:`RepoPath`	Path to repository
object_sha:`str \| ObjectID`	SHA of the object to replace
replacement_sha:`str \| ObjectID`	SHA of the replacement object

def replace_delete(repo: RepoPath, object_sha: ObjectID | str): ¶

Delete a replacement ref.

Parameters
repo:`RepoPath`	Path to repository
object_sha:`ObjectID \| str`	SHA of the object whose replacement should be removed

def replace_list(repo: RepoPath) -> list[tuple[ObjectID, ObjectID]]: ¶

List all replacement refs.

Parameters
repo:`RepoPath`	Path to repository

Returns
`list[tuple[ObjectID, ObjectID]]`	List of tuples of (object_sha, replacement_sha) where object_sha is the object being replaced and replacement_sha is what it's replaced with

def rerere(repo: RepoPath = '.') -> tuple[list[tuple[bytes, str]], list[bytes]]: ¶

Record current conflict resolutions and apply known resolutions.

This reads conflicted files from the working tree and records them in the rerere cache. If rerere.autoupdate is enabled and a known resolution exists, it will be automatically applied.

Parameters
repo:`RepoPath`	Path to the repository

Returns
`Tuple of`	List of tuples (path, conflict_id) for recorded conflicts List of paths where resolutions were automatically applied

def rerere_clear(repo: RepoPath = '.'): ¶

Clear all recorded rerere resolutions.

Parameters
repo:`RepoPath`	Path to the repository

def rerere_diff(repo: RepoPath = '.', conflict_id: str | None = None) -> list[tuple[str, bytes, bytes | None]]: ¶

Show differences for recorded rerere conflicts.

Parameters
repo:`RepoPath`	Path to the repository
conflict_id:`str \| None`	Optional specific conflict ID to show

Returns
`list[tuple[str, bytes, bytes \| None]]`	List of tuples (conflict_id, preimage, postimage)

def rerere_forget(repo: RepoPath = '.', pathspec: str | bytes | None = None): ¶

Forget recorded rerere resolutions for a pathspec.

Parameters
repo:`RepoPath`	Path to the repository
pathspec:`str \| bytes \| None`	Path to forget (currently not implemented, forgets all)

def rerere_gc(repo: RepoPath = '.', max_age_days: int = 60): ¶

Garbage collect old rerere resolutions.

Parameters
repo:`RepoPath`	Path to the repository
max_age_days:`int`	Maximum age in days for keeping resolutions

def rerere_status(repo: RepoPath = '.') -> list[tuple[str, bool]]: ¶

Get the status of all conflicts in the rerere cache.

Parameters
repo:`RepoPath`	Path to the repository

Returns
`list[tuple[str, bool]]`	List of tuples (conflict_id, has_resolution)

Reset current HEAD to the specified state.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to repository
mode:`str`	Mode ("hard", "soft", "mixed")
treeish:`str \| bytes \| Commit \| Tree \| Tag`	Treeish to reset to

Reset the file to specific commit or branch.

Parameters
repo:`Repo`	dulwich Repo object
file_path:`str`	file to reset, relative to the repository path
target:`str \| bytes \| Commit \| Tree \| Tag`	branch or commit or b'HEAD' to reset
symlink_fn:`Callable[[(str \| bytes \| os.PathLike[str]), (str \| bytes \| os.PathLike[str])], None] \| None`	Function to use for creating symlinks

Restore working tree files.

This is similar to 'git restore', allowing you to restore specific files from a commit or the index without changing HEAD.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to repository or repository object
paths:`list[bytes \| str]`	List of specific paths to restore
source:`str \| bytes \| Commit \| Tag \| None`	Branch name, tag, or commit SHA to restore from. If None, restores staged files from HEAD, or worktree files from index
staged:`bool`	Restore files in the index (--staged)
worktree:`bool`	Restore files in the working tree (default: True)

Raises
`CheckoutError`	If restore cannot be performed
`ValueError`	If neither staged nor worktree is specified
`KeyError`	If the source reference cannot be found

def rev_list(repo: RepoPath, commits: Sequence[str | bytes], outstream: BinaryIO = default_bytes_out_stream): ¶

Lists commit objects in reverse chronological order.

Parameters
repo:`RepoPath`	Path to repository
commits:`Sequence[str \| bytes]`	Commits over which to iterate
outstream:`BinaryIO`	Stream to write to

def rev_parse(repo: str | os.PathLike[str] | Repo, rev: str | bytes) -> bytes: ¶

Parse a revision string and return the object SHA.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to the repository or a Repo object
rev:`str \| bytes`	Revision string (e.g., 'HEAD', 'main', 'abc123')

Returns
`bytes`	Object SHA as bytes

Revert one or more commits.

This creates a new commit that undoes the changes introduced by the specified commits. Unlike reset, revert creates a new commit that preserves history.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to repository or repository object
commits:`str \| bytes \| Commit \| Tag \| Sequence[str \| bytes \| Commit \| Tag]`	List of commit-ish (SHA, ref, etc.) to revert, or a single commit-ish
no_commit:`bool`	If True, apply changes to index/working tree but don't commit
message:`str \| bytes \| None`	Optional commit message (default: "Revert <original subject>")
author:`bytes \| None`	Optional author for revert commit
committer:`bytes \| None`	Optional committer for revert commit

Returns
`bytes \| None`	SHA1 of the new revert commit, or None if no_commit=True

Raises
`Error`	If revert fails due to conflicts or other issues

def set_branch_tracking(repo: str | os.PathLike[str] | Repo, branch_name: bytes, remote_name: bytes, remote_ref: bytes): ¶

Set up branch tracking configuration.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Repository to open
branch_name:`bytes`	Name of the local branch
remote_name:`bytes`	Name of the remote (e.g. b"origin")
remote_ref:`bytes`	Remote reference to track (e.g. b"refs/heads/main")

def shortlog(repo: str | os.PathLike[str] | Repo, summary_only: bool = False, sort_by_commits: bool = False) -> list[dict[str, str]]: ¶

Summarize commits by author, like git shortlog.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to repository or Repo object.
summary_only:`bool`	If True, only show counts per author.
sort_by_commits:`bool`	If True, sort authors by number of commits.

Returns
`A list where each item is a dict containing`	"author": the author's name as a string "messages": all commit messages concatenated into a single string

def show(repo: RepoPath = '.', objects: Sequence[str | bytes] | None = None, outstream: TextIO = sys.stdout, default_encoding: str = DEFAULT_ENCODING): ¶

Print the changes in a commit.

Parameters
repo:`RepoPath`	Path to repository
objects:`Sequence[str \| bytes] \| None`	Objects to show (defaults to [HEAD])
outstream:`TextIO`	Stream to write to
default_encoding:`str`	Default encoding to use if none is set in the commit

def show_blob(repo: RepoPath, blob: Blob, decode: Callable[[bytes], str], outstream: TextIO = sys.stdout): ¶

Write a blob to a stream.

Parameters
repo:`RepoPath`	A `Repo` object
blob:`Blob`	A `Blob` object
decode:`Callable[[bytes], str]`	Function for decoding bytes to unicode string
outstream:`TextIO`	A stream file to write to

def show_branch(repo: Repo | str = '.', branches: list[str | bytes] | None = None, all_branches: bool = False, remotes: bool = False, current: bool = False, topo_order: bool = False, more: int | None = None, list_branches: bool = False, independent_branches: bool = False, merge_base: bool = False) -> list[str]: ¶

Display branches and their commits.

Parameters
repo:`Repo \| str`	Path to the repository
branches:`list[str \| bytes] \| None`	List of specific branches to show (default: all local branches)
all_branches:`bool`	Show both local and remote branches
remotes:`bool`	Show only remote branches
current:`bool`	Include current branch if not specified
topo_order:`bool`	Show in topological order instead of chronological
more:`int \| None`	Show N more commits beyond common ancestor (negative to show only headers)
list_branches:`bool`	Synonym for more=-1 (show only branch headers)
independent_branches:`bool`	Show only branches not reachable from others
merge_base:`bool`	Show merge bases instead of commit list

Returns
`list[str]`	List of output lines

def show_commit(repo: RepoPath, commit: Commit, decode: Callable[[bytes], str], outstream: TextIO = sys.stdout): ¶

Show a commit to a stream.

Parameters
repo:`RepoPath`	A `Repo` object
commit:`Commit`	A `Commit` object
decode:`Callable[[bytes], str]`	Function for decoding bytes to unicode string
outstream:`TextIO`	Stream to write to

def show_index(index_path: str | os.PathLike[str], repo: str | os.PathLike[str] | Repo = '.') -> list[tuple[int, RawObjectID, int | None]]: ¶

Show the contents of a pack index file.

Parameters
index_path:`str \| os.PathLike[str]`	Path to the pack index file
repo:`str \| os.PathLike[str] \| Repo`	Path to the repository or a Repo object (for object format)

Returns
`list[tuple[int, RawObjectID, int \| None]]`	List of tuples (offset, sha, crc32) for each entry

Raises
`FileNotFoundError`	If the index file doesn't exist

def show_object(repo: RepoPath, obj: Tree | Blob | Commit | Tag, decode: Callable[[bytes], str], outstream: TextIO): ¶

Show details of a git object.

def show_ref(repo: Repo | str = '.', patterns: list[str | bytes] | None = None, head: bool = False, branches: bool = False, tags: bool = False, dereference: bool = False, verify: bool = False) -> list[tuple[bytes, bytes]]: ¶

List references in a local repository.

Returns: List of tuples with (sha, ref_name) or (sha, ref_name^{}) for dereferenced tags

Parameters
repo:`Repo \| str`	Path to the repository
patterns:`list[str \| bytes] \| None`	Optional list of patterns to filter refs (matched from the end)
head:`bool`	Show the HEAD reference
branches:`bool`	Limit to local branches (refs/heads/)
tags:`bool`	Limit to local tags (refs/tags/)
dereference:`bool`	Dereference tags into object IDs
verify:`bool`	Enable stricter reference checking (exact path match)

Returns
`list[tuple[bytes, bytes]]`	Undocumented

def show_tag(repo: RepoPath, tag: Tag, decode: Callable[[bytes], str], outstream: TextIO = sys.stdout): ¶

Print a tag to a stream.

Parameters
repo:`RepoPath`	A `Repo` object
tag:`Tag`	A `Tag` object
decode:`Callable[[bytes], str]`	Function for decoding bytes to unicode string
outstream:`TextIO`	Stream to write to

def show_tree(repo: RepoPath, tree: Tree, decode: Callable[[bytes], str], outstream: TextIO = sys.stdout): ¶

Print a tree to a stream.

Parameters
repo:`RepoPath`	A `Repo` object
tree:`Tree`	A `Tree` object
decode:`Callable[[bytes], str]`	Function for decoding bytes to unicode string
outstream:`TextIO`	Stream to write to

def sparse_checkout(repo: str | os.PathLike[str] | Repo, patterns: list[str] | None = None, force: bool = False, cone: bool | None = None): ¶

Perform a sparse checkout in the repository (either 'full' or 'cone mode').

Perform sparse checkout in either 'cone' (directory-based) mode or 'full pattern' (.gitignore) mode, depending on the cone parameter.

If cone is None, the mode is inferred from the repository's core.sparseCheckoutCone config setting.

Steps:

If patterns is provided, write them to .git/info/sparse-checkout.
Determine which paths in the index are included vs. excluded. - If cone=True, use "cone-compatible" directory-based logic. - If cone=False, use standard .gitignore-style matching.
Update the index's skip-worktree bits and add/remove files in the working tree accordingly.
If force=False, refuse to remove files that have local modifications.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to the repository or a Repo object.
patterns:`list[str] \| None`	Optional list of sparse-checkout patterns to write.
force:`bool`	Whether to force removal of locally modified files (default False).
cone:`bool \| None`	Boolean indicating cone mode (True/False). If None, read from config.

Returns
None

def stash_drop(repo: str | os.PathLike[str] | Repo, index: int): ¶

Drop a stash from the stack.

def stash_list(repo: str | os.PathLike[str] | Repo) -> Iterator[tuple[int, tuple[bytes, bytes]]]: ¶

List all stashes in a repository.

def stash_pop(repo: str | os.PathLike[str] | Repo): ¶

Pop a stash from the stack.

def stash_push(repo: str | os.PathLike[str] | Repo): ¶

Push a new stash onto the stack.

def status(repo: str | os.PathLike[str] | Repo = '.', ignored: bool = False, untracked_files: str = 'normal') -> GitStatus: ¶

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

Returns: GitStatus tuple,: staged - dict with lists of staged paths (filesystem paths as bytes) unstaged - list of unstaged paths (filesystem paths as bytes) untracked - list of untracked paths (filesystem paths as bytes)

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to repository or repository object
ignored:`bool`	Whether to include ignored files in untracked
untracked_files:`str`	How to handle untracked files, defaults to "all": "no": do not return untracked files "normal": return untracked directories, not their contents "all": include all files in untracked directories Using untracked_files="no" can be faster than "all" when the worktree contains many untracked files/directories. Using untracked_files="normal" provides a good balance, only showing directories that are entirely untracked without listing all their contents.

Returns
`GitStatus`	Undocumented

def stripspace(text: str | bytes, *, strip_comments: bool = False, comment_char: str = '#', comment_lines: bool = False) -> bytes: ¶

Strip unnecessary whitespace from text.

This function implements the functionality of git stripspace, commonly used to clean up commit messages and other text content.

The function performs the following operations:

If comment_lines is True, prepend comment_char + space to each line
Strip trailing whitespace from each line
If strip_comments is True, remove lines starting with comment_char
Collapse multiple consecutive blank lines into a single blank line
Remove leading blank lines
Remove trailing blank lines
Ensure the text ends with a newline (unless empty)

Examples

>>> stripspace(b"  hello  \\n\\n\\nworld  \\n\\n")
b'hello\\n\\nworld\\n'

>>> stripspace(b"# comment\\ntext\\n", strip_comments=True)
b'text\\n'

>>> stripspace(b"line\\n", comment_lines=True)
b'# line\\n'

Parameters
text:`str \| bytes`	The text to process (string or bytes)
strip_comments:`bool`	If True, remove lines that begin with comment_char
comment_char:`str`	The comment character to use (default: "#")
comment_lines:`bool`	If True, prepend comment_char to each line

Returns
`bytes`	The processed text as bytes

Add a new submodule.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to repository
url:`str`	URL of repository to add as submodule
path:`str \| os.PathLike[str] \| None`	Path where submodule should live
name:`str \| None`	Name for the submodule

def submodule_init(repo: str | os.PathLike[str] | Repo): ¶

Initialize submodules.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to repository

def submodule_list(repo: RepoPath) -> Iterator[tuple[str, str]]: ¶

List submodules.

Parameters
repo:`RepoPath`	Path to repository

Returns
`Iterator[tuple[str, str]]`	Undocumented

Update submodules.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to repository
paths:`Sequence[str \| bytes \| os.PathLike[str]] \| None`	Optional list of specific submodule paths to update. If None, updates all.
init:`bool`	If True, initialize submodules first
force:`bool`	Force update even if local changes exist
recursive:`bool`	If True, recursively update nested submodules
errstream:`BinaryIO \| None`	Error stream for error messages

Switch branches.

This is similar to 'git switch', allowing you to switch to a different branch or commit, updating both HEAD and the working tree.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to repository or repository object
target:`str \| bytes \| Commit \| Tag`	Branch name, tag, or commit SHA to switch to
create:`str \| bytes \| None`	Create a new branch at target before switching (like git switch -c)
force:`bool`	Force switch even if there are local changes
detach:`bool`	Switch to a commit in detached HEAD state (like git switch --detach)

Raises
`CheckoutError`	If switch cannot be performed due to conflicts
`KeyError`	If the target reference cannot be found
`ValueError`	If both create and detach are specified

def symbolic_ref(repo: RepoPath, ref_name: str | bytes, force: bool = False): ¶

Set git symbolic ref into HEAD.

Parameters
repo:`RepoPath`	path to the repository
ref_name:`str \| bytes`	short name of the new ref
force:`bool`	force settings without checking if it exists in refs/heads

Creates a tag in git via dulwich calls.

Parameters
repo:`RepoPath`	Path to repository
tag:`str \| bytes`	tag string
author:`str \| bytes \| None`	tag author (optional, if annotated is set)
message:`str \| bytes \| None`	tag message (optional)
annotated:`bool`	whether to create an annotated tag
objectish:`str \| bytes`	object the tag should point at, defaults to HEAD
tag_time:`int \| None`	Optional time for annotated tag
tag_timezone:`int \| None`	Optional timezone for annotated tag
sign:`bool \| None`	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:`str \| None`	Encoding to use for tag messages

def tag_delete(repo: RepoPath, name: str | bytes): ¶

Remove a tag.

Parameters
repo:`RepoPath`	Path to repository
name:`str \| bytes`	Name of tag to remove

def tag_list(repo: RepoPath, outstream: TextIO = sys.stdout) -> list[Ref]: ¶

List all tags.

Parameters
repo:`RepoPath`	Path to repository
outstream:`TextIO`	Stream to write tags to

Returns
`list[Ref]`	Undocumented

def tree_path_to_fs_path(tree_path: bytes, tree_encoding: str = DEFAULT_ENCODING) -> bytes: ¶

Convert a git tree path to a filesystem path (relative).

Returns: Filesystem path as bytes (with os.sep, filesystem encoding)

Parameters
tree_path:`bytes`	Path from git tree (bytes with "/" separators, UTF-8 encoded)
tree_encoding:`str`	Encoding used for tree paths (default: utf-8)

Returns
`bytes`	Undocumented

def unpack_objects(pack_path: str | os.PathLike[str], target: str | os.PathLike[str] = '.') -> int: ¶

Unpack objects from a pack file into the repository.

Parameters
pack_path:`str \| os.PathLike[str]`	Path to the pack file to unpack
target:`str \| os.PathLike[str]`	Path to the repository to unpack into

Returns
`int`	Number of objects unpacked

def update_head(repo: RepoPath, target: str | bytes, detached: bool = False, new_branch: str | bytes | None = None): ¶

Update HEAD to point at a new branch/commit.

Note that this does not actually update the working tree.

Parameters
repo:`RepoPath`	Path to the repository
target:`str \| bytes`	Branch or committish to switch to
detached:`bool`	Create a detached head
new_branch:`str \| bytes \| None`	New branch to create

Update the object name stored in a ref safely.

Parameters
repo:`str \| os.PathLike[str] \| Repo`	Path to the repository or a Repo object
ref:`str \| bytes`	Name of the ref to update (e.g., 'refs/heads/main', 'HEAD')
new_value:`str \| bytes \| None`	New object SHA to set the ref to (None to delete)
old_value:`str \| bytes \| None`	Optional old value to verify before updating (for atomic updates)
message:`str \| bytes \| None`	Optional message for the reflog

Raises
`ValueError`	If the old value doesn't match

def update_server_info(repo: RepoPath = '.'): ¶

Update server info files for a repository.

Parameters
repo:`RepoPath`	path to the repository

def upload_pack(path: str | os.PathLike[str] = '.', inf: BinaryIO | None = None, outf: BinaryIO | None = None) -> int: ¶

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

Parameters
path:`str \| os.PathLike[str]`	Path to the repository
inf:`BinaryIO \| None`	Input stream to communicate with client
outf:`BinaryIO \| None`	Output stream to communicate with client

Returns
`int`	Undocumented

def var(repo: RepoPath = '.', variable: str = 'GIT_AUTHOR_IDENT') -> str: ¶

Get the value of a specific Git logical variable.

Parameters
repo:`RepoPath`	Path to the repository
variable:`str`	The variable to query (e.g., 'GIT_AUTHOR_IDENT')

Returns
`str`	The value of the requested variable as a string

Raises
`KeyError`	If the requested variable has no value

def var_list(repo: RepoPath = '.') -> dict[str, str]: ¶

List all Git logical variables.

Parameters
repo:`RepoPath`	Path to the repository

Returns
`dict[str, str]`	A dictionary of all logical variables with their values

def verify_commit(repo: RepoPath, committish: str | bytes = 'HEAD', keyids: list[str] | None = None): ¶

Verify signature on a commit.

Parameters
repo:`RepoPath`	Path to repository
committish:`str \| bytes`	Commit to verify (defaults to HEAD)
keyids:`list[str] \| None`	Optional list of trusted key IDs. If provided, the commit must be signed by one of these keys. If not provided, just verifies that the commit has a valid signature.

Raises
`gpg.errors.BadSignatures`	if GPG signature verification fails
`gpg.errors.MissingSignatures`	if commit was not signed by a key specified in keyids

def verify_tag(repo: RepoPath, tagname: str | bytes, keyids: list[str] | None = None): ¶

Verify signature on a tag.

Parameters
repo:`RepoPath`	Path to repository
tagname:`str \| bytes`	Name of tag to verify
keyids:`list[str] \| None`	Optional list of trusted key IDs. If provided, the tag must be signed by one of these keys. If not provided, just verifies that the tag has a valid signature.

Raises
`gpg.errors.BadSignatures`	if GPG signature verification fails
`gpg.errors.MissingSignatures`	if tag was not signed by a key specified in keyids

def web_daemon(path: str | os.PathLike[str] = '.', address: str | None = None, port: int | None = None): ¶

Run a daemon serving Git requests over HTTP.

Parameters
path:`str \| os.PathLike[str]`	Path to the directory to serve
address:`str \| None`	Optional address to listen on (defaults to ::)
port:`int \| None`	Optional port to listen on (defaults to 80)

Add a new worktree.

Parameters
repo:`RepoPath`	Path to repository
path:`str \| os.PathLike[str] \| None`	Path for new worktree
branch:`str \| bytes \| None`	Branch to checkout (creates if doesn't exist)
commit:`str \| bytes \| None`	Specific commit to checkout
detach:`bool`	Create with detached HEAD
force:`bool`	Force creation even if branch is already checked out

Returns
`str`	Path to the newly created worktree

def worktree_list(repo: RepoPath = '.') -> list[WorkTreeInfo]: ¶

List all worktrees for a repository.

Parameters
repo:`RepoPath`	Path to repository

Returns
`list[WorkTreeInfo]`	List of WorkTreeInfo objects

def worktree_lock(repo: RepoPath = '.', path: str | os.PathLike[str] | None = None, reason: str | None = None): ¶

Lock a worktree to prevent it from being pruned.

Parameters
repo:`RepoPath`	Path to repository
path:`str \| os.PathLike[str] \| None`	Path to worktree to lock
reason:`str \| None`	Optional reason for locking

def worktree_move(repo: RepoPath = '.', old_path: str | os.PathLike[str] | None = None, new_path: str | os.PathLike[str] | None = None): ¶

Move a worktree to a new location.

Parameters
repo:`RepoPath`	Path to repository
old_path:`str \| os.PathLike[str] \| None`	Current path of worktree
new_path:`str \| os.PathLike[str] \| None`	New path for worktree

def worktree_prune(repo: RepoPath = '.', dry_run: bool = False, expire: int | None = None) -> list[str]: ¶

Prune worktree administrative files.

Parameters
repo:`RepoPath`	Path to repository
dry_run:`bool`	Only show what would be removed
expire:`int \| None`	Only prune worktrees older than this many seconds

Returns
`list[str]`	List of pruned worktree names

def worktree_remove(repo: RepoPath = '.', path: str | os.PathLike[str] | None = None, force: bool = False): ¶

Remove a worktree.

Parameters
repo:`RepoPath`	Path to repository
path:`str \| os.PathLike[str] \| None`	Path to worktree to remove
force:`bool`	Force removal even if there are local changes

def worktree_repair(repo: RepoPath = '.', paths: list[str | os.PathLike[str]] | None = None) -> list[str]: ¶

Repair worktree administrative files.

Parameters
repo:`RepoPath`	Path to repository
paths:`list[str \| os.PathLike[str]] \| None`	Optional list of worktree paths to repair. If None, repairs connections from the main repository to all linked worktrees.

Returns
`list[str]`	List of repaired worktree paths

def worktree_unlock(repo: RepoPath = '.', path: str | os.PathLike[str] | None = None): ¶

Unlock a worktree.

Parameters
repo:`RepoPath`	Path to repository
path:`str \| os.PathLike[str] \| None`	Path to worktree to unlock

def write_commit_graph(repo: RepoPath = '.', reachable: bool = True): ¶

Write a commit graph file for a repository.

Parameters
repo:`RepoPath`	path to the repository or a Repo object
reachable:`bool`	if True, include all commits reachable from refs. if False, only include direct ref targets.

def write_tree(repo: RepoPath) -> bytes: ¶

Write a tree object from the index.

Returns: tree id for the tree that was written

Parameters
repo:`RepoPath`	Repository for which to write tree

Returns
`bytes`	Undocumented

DEFAULT_ENCODING: str = ¶

Undocumented

Value

'utf-8'

INFINITE_DEPTH: int = ¶

Undocumented

Value

2147483647

T = ¶

Undocumented

Value

TypeVar('T',
        bound='BaseRepo')

default_bytes_err_stream: BinaryIO = ¶

Undocumented

default_bytes_out_stream: BinaryIO = ¶

Undocumented

GitStatus = ¶

Undocumented

RepoPath = ¶

Undocumented

def _canonical_part(url: str) -> str: ¶

Undocumented

def _check_uncommitted_changes(repo: Repo, target_tree_id: ObjectID, force: bool = False): ¶

Check for uncommitted changes that would conflict with a checkout/switch.

Parameters
repo:`Repo`	Repository object
target_tree_id:`ObjectID`	Tree ID to check conflicts against
force:`bool`	If True, skip the check

Raises
`CheckoutError`	If there are conflicting local changes

def _do_merge(r: Repo, merge_commit_id: ObjectID, no_commit: bool = False, no_ff: bool = False, message: bytes | None = None, author: bytes | None = None, committer: bytes | None = None) -> tuple[ObjectID | None, list[bytes]]: ¶

Internal merge implementation that operates on an open repository.

Parameters
r:`Repo`	Open repository object
merge_commit_id:`ObjectID`	SHA of commit to merge
no_commit:`bool`	If True, do not create a merge commit
no_ff:`bool`	If True, force creation of a merge commit
message:`bytes \| None`	Optional merge commit message
author:`bytes \| None`	Optional author for merge commit
committer:`bytes \| None`	Optional committer for merge commit

Returns
`tuple[ObjectID \| None, list[bytes]]`	Tuple of (merge_commit_sha, conflicts) where merge_commit_sha is None if no_commit=True or there were conflicts

def _do_octopus_merge(r: Repo, merge_commit_ids: list[ObjectID], no_commit: bool = False, no_ff: bool = False, message: bytes | None = None, author: bytes | None = None, committer: bytes | None = None) -> tuple[ObjectID | None, list[bytes]]: ¶

Internal octopus merge implementation that operates on an open repository.

Parameters
r:`Repo`	Open repository object
merge_commit_ids:`list[ObjectID]`	List of commit SHAs to merge
no_commit:`bool`	If True, do not create a merge commit
no_ff:`bool`	If True, force creation of a merge commit (ignored for octopus)
message:`bytes \| None`	Optional merge commit message
author:`bytes \| None`	Optional author for merge commit
committer:`bytes \| None`	Optional committer for merge commit

Returns
`tuple[ObjectID \| None, list[bytes]]`	Tuple of (merge_commit_sha, conflicts) where merge_commit_sha is None if no_commit=True or there were conflicts

def _filter_transport_kwargs(**kwargs: object) -> TransportKwargs: ¶

Filter kwargs to only include parameters accepted by get_transport_and_path.

Parameters
**kwargs:`object`	Arbitrary keyword arguments

Returns
`TransportKwargs`	Dictionary containing only the kwargs that get_transport_and_path accepts

def _find_reachable_tags(r: BaseRepo, pushed_shas: set[ObjectID], already_included: set[Ref], remote_refs: dict[Ref, ObjectID]) -> Iterator[tuple[Ref, ObjectID]]: ¶

Yield annotated tags whose targets are reachable from pushed commits.

Parameters
r:`BaseRepo`	Local repository
pushed_shas:`set[ObjectID]`	SHAs being pushed (non-deletion)
already_included:`set[Ref]`	Refs already being pushed
remote_refs:`dict[Ref, ObjectID]`	Current remote refs

Returns
`Iterator[tuple[Ref, ObjectID]]`	Undocumented

def _get_branch_merge_status(repo: RepoPath) -> Iterator[tuple[bytes, bool]]: ¶

Get merge status for all branches relative to current HEAD.

Parameters
repo:`RepoPath`	Path to the repository

Returns
`Iterator[tuple[bytes, bool]]`	Undocumented

Yields
`tuple of (branch_name, is_merged) where`	`branch_name`: Branch name without refs/heads/ prefix `is_merged`: True if branch is merged into HEAD, False otherwise

def _get_current_head_tree(repo: Repo) -> ObjectID | None: ¶

Get the current HEAD tree ID.

Parameters
repo:`Repo`	Repository object

Returns
`ObjectID \| None`	Tree ID of current HEAD, or None if no HEAD exists (empty repo)

def _get_reflog_message(default_message: bytes, explicit_message: bytes | None = None) -> bytes: ¶

Get reflog message, checking GIT_REFLOG_ACTION environment variable.

Parameters
default_message:`bytes`	Default message to use if no explicit message or env var
explicit_message:`bytes \| None`	Explicit message passed as argument (takes precedence)

Returns
`The reflog message with priority`	explicit_message if provided GIT_REFLOG_ACTION environment variable if set default_message otherwise

def _get_variables(repo: RepoPath = '.') -> dict[str, str]: ¶

Internal function to get all Git logical variables.

Parameters
repo:`RepoPath`	Path to the repository

Returns
`dict[str, str]`	A dictionary of all logical variables with values

def _get_worktree_update_config(repo: Repo) ->

tuple[bool, Callable[[bytes], bool], Callable[[(str | bytes | os.PathLike[str]), (str | bytes | os.PathLike[str])], None]]

: ¶

Get configuration for working tree updates.

Parameters
repo:`Repo`	Repository object

Returns
`tuple[bool, Callable[[bytes], bool], Callable[[(str \| bytes \| os.PathLike[str]), (str \| bytes \| os.PathLike[str])], None]]`	Tuple of (honor_filemode, validate_path_element, symlink_fn)

def _is_subdir(subdir: str | os.PathLike[str], parentdir: str | os.PathLike[str]) -> bool: ¶

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: str | bytes) -> Ref: ¶

Undocumented

def _make_replace_ref(name: str | bytes | ObjectID) -> Ref: ¶

Undocumented

@contextmanager

def _noop_context_manager(obj: T) -> Iterator[T]: ¶

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

def _perform_tree_switch(repo: Repo, current_tree_id: ObjectID | None, target_tree_id: ObjectID, force: bool = False): ¶

Perform the actual working tree switch.

Parameters
repo:`Repo`	Repository object
current_tree_id:`ObjectID \| None`	Current tree ID (or None for empty repo)
target_tree_id:`ObjectID`	Target tree ID to switch to
force:`bool`	If True, force removal of untracked files and allow overwriting modified files

def _precompose_unicode_path(path: str) -> str: ¶

Normalize a filesystem path to NFC (precomposed) Unicode form.

On macOS, HFS+/APFS filesystems return filenames in NFD (decomposed) form. This function normalizes them to NFC so they match the paths stored in the git index.

def _quote_path(path: str) -> str: ¶

Quote a path using C-style quoting similar to git's core.quotePath.

Parameters
path:`str`	Path to quote

Returns
`str`	Quoted path string

Select which refs to push based on mode flags or user refspecs.

Returns a list of (local_ref, remote_ref, force) tuples. local_ref is None for deletions.

Parameters
r:`BaseRepo`	Local repository
remote_refs:`dict[Ref, ObjectID]`	Current remote refs dict
refspecs:`str \| bytes \| Sequence[str \| bytes] \| None`	User-provided refspecs (may be None)
force:`bool`	Force overwriting refs
mirror_mode:`bool`	Push all refs
all:`bool`	Push all branches
tags:`bool`	Push all tags
delete:`bool`	Delete the specified remote refs

Returns
`list[tuple[Ref \| None, Ref \| None, bool]]`	Undocumented

Get path, is_dir for files in working dir from frompath.

Parameters
frompath:`str \| bytes \| os.PathLike[str]`	Path to begin walk
basepath:`str \| bytes \| os.PathLike[str]`	Path to compare to
prune_dirnames:`Callable[[str, list[str]], list[str]] \| None`	Optional callback to prune dirnames during os.walk dirnames will be set to result of prune_dirnames(dirpath, dirnames)
precompose_unicode:`bool`	If True, normalize paths to NFC Unicode form

Returns
`Iterator[tuple[str \| bytes, bool]]`	Undocumented