dulwich.cli

module documentation

Simple command-line interface to Dulwich>.

This is a very simple command-line wrapper for Dulwich. It is by no means intended to be a full-blown Git command-line interface but just a way to test Dulwich.

Class	`AutoFlushBinaryIOWrapper`	Wrapper that automatically flushes a BinaryIO stream based on configuration.
Class	`AutoFlushTextIOWrapper`	Wrapper that automatically flushes a TextIO stream based on configuration.
Class	`cmd_add`	Add file contents to the index.
Class	`cmd_am`	Apply patches from mailbox-style email messages.
Class	`cmd_annotate`	Annotate each line in a file with commit information.
Class	`cmd_apply`	Apply a patch to files and/or to the index.
Class	`cmd_archive`	Create an archive of files from a named tree.
Class	`cmd_bisect`	Use binary search to find the commit that introduced a bug.
Class	`cmd_blame`	Show what revision and author last modified each line of a file.
Class	`cmd_branch`	List, create, or delete branches.
Class	`cmd_bundle`	Create, unpack, and manipulate bundle files.
Class	`cmd_cat_file`	Provide content or type and size information for repository objects.
Class	`cmd_check_ignore`	Check whether files are excluded by gitignore.
Class	`cmd_check_mailmap`	Show canonical names and email addresses of contacts.
Class	`cmd_checkout`	Switch branches or restore working tree files.
Class	`cmd_cherry`	Find commits not merged upstream.
Class	`cmd_cherry_pick`	Apply the changes introduced by some existing commits.
Class	`cmd_clean`	Remove untracked files from the working tree.
Class	`cmd_clone`	Clone a repository into a new directory.
Class	`cmd_column`	Display data in columns.
Class	`cmd_commit`	Record changes to the repository.
Class	`cmd_commit_tree`	Create a new commit object from a tree.
Class	`cmd_config`	Get and set repository or global options.
Class	`cmd_count_objects`	Count unpacked number of objects and their disk consumption.
Class	`cmd_daemon`	Run a simple Git protocol server.
Class	`cmd_describe`	Give an object a human readable name based on an available ref.
Class	`cmd_diagnose`	Display diagnostic information about the Python environment.
Class	`cmd_diff`	Show changes between commits, commit and working tree, etc.
Class	`cmd_diff_tree`	Compare the content and mode of trees.
Class	`cmd_dump_index`	Show information about a pack index file.
Class	`cmd_dump_pack`	Dump the contents of a pack file for debugging.
Class	`cmd_fetch`	Download objects and refs from another repository.
Class	`cmd_fetch_pack`	Receive missing objects from another repository.
Class	`cmd_filter_branch`	Rewrite branches.
Class	`cmd_for_each_ref`	Output information on each ref.
Class	`cmd_format_patch`	Prepare patches for e-mail submission.
Class	`cmd_fsck`	Verify the connectivity and validity of objects in the database.
Class	`cmd_gc`	Cleanup unnecessary files and optimize the local repository.
Class	`cmd_grep`	Search for patterns in tracked files.
Class	`cmd_hash_object`	Compute object ID and optionally store in repository.
Class	`cmd_help`	Display help information about git.
Class	`cmd_init`	Create an empty Git repository or reinitialize an existing one.
Class	`cmd_interpret_trailers`	Add or parse structured information in commit messages.
Class	`cmd_lfs`	Git Large File Storage management.
Class	`cmd_log`	Show commit logs.
Class	`cmd_ls_files`	Show information about files in the index and working tree.
Class	`cmd_ls_remote`	List references in a remote repository.
Class	`cmd_ls_tree`	List the contents of a tree object.
Class	`cmd_mailinfo`	Extract patch information from an email message.
Class	`cmd_mailsplit`	Split mbox or Maildir into individual message files.
Class	`cmd_maintenance`	Run tasks to optimize Git repository data.
Class	`cmd_merge`	Join two or more development histories together.
Class	`cmd_merge_base`	Find the best common ancestor between commits.
Class	`cmd_merge_tree`	Show three-way merge without touching index.
Class	`cmd_mktag`	Create a tag object from raw tag data.
Class	`cmd_mv`	Move or rename a file, a directory, or a symlink.
Class	`cmd_notes`	Add or inspect object notes.
Class	`cmd_notes_add`	Add notes to a commit.
Class	`cmd_notes_list`	List all note objects.
Class	`cmd_notes_remove`	Remove notes for a commit.
Class	`cmd_notes_show`	Show notes for a commit.
Class	`cmd_pack_objects`	Create a packed archive of objects.
Class	`cmd_pack_refs`	Pack heads and tags for efficient repository access.
Class	`cmd_prune`	Prune all unreachable objects from the object database.
Class	`cmd_pull`	Fetch from and integrate with another repository or a local branch.
Class	`cmd_push`	Update remote refs along with associated objects.
Class	`cmd_rebase`	Reapply commits on top of another base tip.
Class	`cmd_receive_pack`	Receive what is pushed into the repository.
Class	`cmd_reflog`	Manage reflog information.
Class	`cmd_remote`	Manage set of tracked repositories.
Class	`cmd_remote_add`	Add a remote repository.
Class	`cmd_repack`	Pack unpacked objects in a repository.
Class	`cmd_replace`	Create, list, and delete replacement refs.
Class	`cmd_replace_delete`	Delete a replacement ref.
Class	`cmd_replace_list`	List all replacement refs.
Class	`cmd_rerere`	Record and reuse recorded conflict resolutions.
Class	`cmd_reset`	Reset current HEAD to the specified state.
Class	`cmd_restore`	Restore working tree files.
Class	`cmd_rev_list`	List commit objects in reverse chronological order.
Class	`cmd_rev_parse`	Parse revision and other objects.
Class	`cmd_revert`	Revert some existing commits.
Class	`cmd_rm`	Remove files from the working tree and from the index.
Class	`cmd_shortlog`	Show a shortlog of commits by author.
Class	`cmd_show`	Show various types of objects.
Class	`cmd_show_branch`	Show branches and their commits.
Class	`cmd_show_index`	Show packed archive index.
Class	`cmd_show_ref`	List references in a local repository.
Class	`cmd_sparse_checkout`	Manage sparse checkout.
Class	`cmd_sparse_checkout_add`	Add directories to sparse checkout.
Class	`cmd_sparse_checkout_disable`	Disable sparse checkout.
Class	`cmd_sparse_checkout_init`	Initialize sparse checkout in cone mode.
Class	`cmd_sparse_checkout_list`	List sparse checkout patterns.
Class	`cmd_sparse_checkout_set`	Set sparse checkout directories.
Class	`cmd_stash`	Stash the changes in a dirty working directory away.
Class	`cmd_stash_list`	List stash entries.
Class	`cmd_stash_pop`	Apply a stash and remove it from the stash list.
Class	`cmd_stash_push`	Save your local modifications to a new stash.
Class	`cmd_status`	Show the working tree status.
Class	`cmd_stripspace`	Remove unnecessary whitespace from text.
Class	`cmd_submodule`	Initialize, update or inspect submodules.
Class	`cmd_submodule_add`	Add a submodule.
Class	`cmd_submodule_init`	Initialize submodules.
Class	`cmd_submodule_list`	List submodules.
Class	`cmd_submodule_update`	Update submodules.
Class	`cmd_subtree`	Manage subtrees within a repository.
Class	`cmd_subtree_add`	Add a subtree.
Class	`cmd_subtree_merge`	Merge changes into a subtree.
Class	`cmd_subtree_pull`	Pull changes from a remote repository into a subtree.
Class	`cmd_subtree_push`	Push a subtree to a remote repository.
Class	`cmd_subtree_split`	Split a subtree into a separate branch.
Class	`cmd_switch`	Switch branches.
Class	`cmd_symbolic_ref`	Read, modify and delete symbolic refs.
Class	`cmd_tag`	Create, list, delete or verify a tag object.
Class	`cmd_unpack_objects`	Unpack objects from a packed archive.
Class	`cmd_update_ref`	Update the object name stored in a ref safely.
Class	`cmd_update_server_info`	Update auxiliary info file to help dumb servers.
Class	`cmd_upload_pack`	Send objects packed back to git-fetch-pack.
Class	`cmd_var`	Display Git logical variables.
Class	`cmd_verify_commit`	Check the GPG signature of commits.
Class	`cmd_verify_tag`	Check the GPG signature of tags.
Class	`cmd_web_daemon`	Run a simple HTTP server for Git repositories.
Class	`cmd_worktree`	Manage multiple working trees.
Class	`cmd_worktree_add`	Create a new worktree.
Class	`cmd_worktree_list`	List worktrees.
Class	`cmd_worktree_lock`	Lock a worktree to prevent it from being pruned.
Class	`cmd_worktree_move`	Move a worktree to a new location.
Class	`cmd_worktree_prune`	Prune worktree information.
Class	`cmd_worktree_remove`	Remove a worktree.
Class	`cmd_worktree_repair`	Repair worktree administrative files.
Class	`cmd_worktree_unlock`	Unlock a locked worktree.
Class	`cmd_write_tree`	Create a tree object from the current index.
Class	`Command`	A Dulwich subcommand.
Class	`Pager`	File-like object that pages output through external pager programs.
Class	`PagerBuffer`	Binary buffer wrapper for Pager to mimic sys.stdout.buffer.
Class	`SuperCommand`	Base class for commands that have subcommands.
Exception	`CommitMessageError`	Raised when there's an issue with the commit message.
Function	`detect_terminal_width`	Detect the width of the terminal.
Function	`disable_pager`	Disable pager for this session.
Function	`enable_pager`	Enable pager for this session.
Function	`format_bytes`	Format bytes as human-readable string.
Function	`format_columns`	Format items into columns with various layout modes.
Function	`get_pager`	Get a pager instance if paging should be used, otherwise return sys.stdout.
Function	`launch_editor`	Launch an editor for the user to enter text.
Function	`main`	Main entry point for the Dulwich CLI.
Function	`parse_time_to_timestamp`	Parse a time specification and return a Unix timestamp.
Function	`signal_int`	Handle interrupt signal by exiting.
Function	`signal_quit`	Handle quit signal by entering debugger.
Function	`to_display_str`	Convert a bytes or string value to a display string.
Function	`write_columns`	Display items in formatted columns based on terminal width.
Variable	`commands`	Undocumented
Variable	`logger`	Undocumented
Class	`_StreamContextAdapter`	Adapter to make streams work with context manager protocol.
Function	`_get_commit_message_with_template`	Get commit message with an initial message template.
Function	`_main`	Undocumented
Function	`_protocol_version_from_env`	Parse the version from the `GIT_PROTOCOL` environment variable.
Function	`_should_auto_flush`	Determine if output should be auto-flushed based on GIT_FLUSH environment variable.
Function	`_ssh_command_from_env`	Return the ssh command requested via `GIT_SSH_COMMAND` / `GIT_SSH`.

def detect_terminal_width() -> int: ¶

Detect the width of the terminal.

Returns
`int`	Width of the terminal in characters, or 80 if it cannot be determined

def disable_pager(): ¶

Disable pager for this session.

def enable_pager(): ¶

Enable pager for this session.

def format_bytes(bytes: float) -> str: ¶

Format bytes as human-readable string.

Parameters
bytes:`float`	Number of bytes

Returns
`str`	Human-readable string like "1.5 MB"

def format_columns(items: list[str], width: int | None = None, mode: str = 'column', padding: int = 1, indent: str = '', nl: str = '\n') -> str: ¶

Format items into columns with various layout modes.

Examples

>>> format_columns(["a", "b", "c"], width=20, mode="column")
"a  b\\nc\\n"
>>> format_columns(["a", "b", "c"], width=20, mode="row")
"a  b  c\\n"

Parameters
items:`list[str]`	List of strings to format
width:`int \| None`	Terminal width (auto-detected if None)
mode:`str`	Layout mode - "column" (fill columns first), "row" (fill rows first), "plain" (one column), or add ",dense" for unequal column widths
padding:`int`	Number of spaces between columns
indent:`str`	String to prepend to each line
nl:`str`	String to append to each line (including newline)

Returns
`str`	Formatted string with items in columns

def get_pager(config: Config | None = None, cmd_name: str | None = None) -> _StreamContextAdapter | Pager: ¶

Get a pager instance if paging should be used, otherwise return sys.stdout.

Parameters
config:`Config \| None`	Optional config instance (e.g., StackedConfig) to read settings from
cmd_name:`str \| None`	Optional command name for per-command pager settings

Returns
`_StreamContextAdapter \| Pager`	Either a wrapped sys.stdout or a Pager instance (both context managers)

def launch_editor(template_content: bytes = b'') -> bytes: ¶

Launch an editor for the user to enter text.

Parameters
template_content:`bytes`	Initial content for the editor

Returns
`bytes`	The edited content as bytes

def main(argv: Sequence[str] | None = None) -> int | None: ¶

Main entry point for the Dulwich CLI.

Parameters
argv:`Sequence[str] \| None`	Command line arguments (defaults to sys.argv[1:])

Returns
`int \| None`	Exit code or None

def parse_time_to_timestamp(time_spec: str) -> int: ¶

Parse a time specification and return a Unix timestamp.

Parameters
time_spec:`str`	Time specification. Can be: - A Unix timestamp (integer as string) - A relative time like "2 weeks ago" - "now" for current time - "all" to expire all entries (returns future time) - "never" to never expire (returns 0 - epoch start)

Returns
`int`	Unix timestamp

Raises
`ValueError`	If the time specification cannot be parsed

def signal_int(signal: int, frame: types.FrameType | None): ¶

Handle interrupt signal by exiting.

Parameters
signal:`int`	Signal number
frame:`types.FrameType \| None`	Current stack frame

def signal_quit(signal: int, frame: types.FrameType | None): ¶

Handle quit signal by entering debugger.

Parameters
signal:`int`	Signal number
frame:`types.FrameType \| None`	Current stack frame

def to_display_str(value: bytes | str) -> str: ¶

Convert a bytes or string value to a display string.

Parameters
value:`bytes \| str`	The value to convert (bytes or str)

Returns
`str`	A string suitable for display

def write_columns(items: Iterator[bytes] | Sequence[bytes], out: TextIO, width: int | None = None): ¶

Display items in formatted columns based on terminal width.

The function calculates the optimal number of columns to fit the terminal width and displays the items in a formatted column layout with proper padding and alignment.

Parameters
items:`Iterator[bytes] \| Sequence[bytes]`	List or iterator of bytes objects to display in columns
out:`TextIO`	Output stream to write to
width:`int \| None`	Optional width of the terminal (if None, auto-detect)

commands = ¶

Undocumented

logger = ¶

Undocumented

def _get_commit_message_with_template(initial_message: bytes | None, repo: Repo | None = None, commit: Commit | None = None) -> bytes: ¶

Get commit message with an initial message template.

def _main(): ¶

Undocumented

def _protocol_version_from_env() -> int | None: ¶

Parse the version from the GIT_PROTOCOL environment variable.

Git uses a colon-separated key=value format for GIT_PROTOCOL (for example version=2 or feature=extra:version=2). Return the requested version as an int when present and parseable, otherwise None.

Env lookup lives here in the CLI layer rather than in the transport library so that dulwich.client and dulwich.porcelain remain process-environment-free.

def _should_auto_flush(stream: TextIO | BinaryIO, env: Mapping[str, str] | None = None) -> bool: ¶

Determine if output should be auto-flushed based on GIT_FLUSH environment variable.

Parameters
stream:`TextIO \| BinaryIO`	The output stream to check
env:`Mapping[str, str] \| None`	Environment variables dict (defaults to os.environ)

Returns
`bool`	True if output should be flushed after each write, False otherwise

def _ssh_command_from_env() -> str | None: ¶

Return the ssh command requested via GIT_SSH_COMMAND / GIT_SSH.

GIT_SSH_COMMAND wins over GIT_SSH, matching git's own precedence. Returns None when neither is set, so callers can fall through to the core.sshCommand config or the transport default.

Env lookup lives here in the CLI layer rather than in the transport library so that dulwich.client stays process-environment-free.