API Reference

Classes 

class pygitx.CommitInfo

Lightweight, read-only view of a git commit.

id: str: Full commit SHA.

summary: str | None: One-line summary if present.

author: str: Author name.

email: str | None: Author email.

time: int: Commit time (seconds since epoch).

offset_minutes: int: Timezone offset in minutes.

class pygitx.RewriteResult

Result of a history rewrite.

old_to_new: dict[str, str]: Mapping of original commit ids to rewritten commit ids.

updated_refs: dict[str, str]: References (e.g., HEAD or refs/heads/main) updated to rewritten commits.

warnings: list[str]: Non-fatal warnings emitted during the rewrite.

class pygitx.DiffStat

Summary of changes between two revisions.

files_changed: int

insertions: int

deletions: int

paths: list[str]

class pygitx.RepoSummary

Lightweight summary of a repository.

path: str

head: str | None

branch: str | None

commits: int

branches: int

tags: int

remotes: int

authors: int

files: int

size_kb: int

is_dirty: bool

last_commit_time: int | None

class pygitx.Repo

Thin wrapper around a git repository.

head() → CommitInfo | None: Return the current HEAD commit, or None if HEAD is unborn/detached without a commit.

summary() → RepoSummary: Return a structured summary (also used by __str__/__repr__).

render_refs(local: bool = True, remote: bool = False, tags: bool = True, max_width: int | None = None, color: bool = False) → str: Render branches/tags in a jj-style table (NAME, OID7, AGE, AUTHOR, SUMMARY), width-aware; enable color for ANSI styling.

render_log(rev: str, max_commits: int = 200, decorate: bool = True, graph: bool = True, max_width: int | None = None, color: bool = False) → str: Render a compact log like git log --graph --oneline with optional decorations and ASCII graph; color toggles ANSI output.

log_graph(refs: list[str] | None = None, max_commits: int = 400, decorate: bool = True, max_width: int | None = None, color: bool = True) → str: Render a multi-branch graph starting from the given refs (or all local branches) with decorations; color toggles ANSI output. (Alias of render_log_graph).

diff_stat(a_spec: str, b_spec: str, paths: list[str] | None = None) → DiffStat: Compute diff statistics between two revisions (optionally limited to paths).

rev_parse(spec: str) → str: Resolve a revision string (e.g., HEAD, HEAD~1, branch/tag, or full/short oid) to a hex object id.

list_commits(max: int | None = None) → list[CommitInfo]: Commits reachable from HEAD (newest first). Pass max to limit results.

change_commit_message(commit_id: str, new_message: str) → RewriteResult: Amend HEAD with a new message (rewrites history). commit_id must resolve to HEAD.

reword(commit_id: str, new_message: str) → RewriteResult: Reword an arbitrary commit on the current branch (linear history only). Traverses the first-parent chain from HEAD to the target and replays commits with the updated message.

list_branches(local: bool = True, remote: bool = False) → list[str]: List branch names. Control inclusion with local/remote flags.

list_tags() → list[str]: List tag names (lightweight/annotated).

current_branch() → str | None: Return the current branch name, or None if detached/unborn.

merge_base(a_spec: str, b_spec: str) → str | None: Compute merge base between two revisions (hex oid or None).

is_ancestor(a_spec: str, b_spec: str) → bool: Return True if a_spec is an ancestor of b_spec.

ahead_behind(a_spec: str, b_spec: str) → tuple[int, int]: Return (ahead, behind) counts comparing a_spec to b_spec.

rewrite_author(commit_id: str, new_name: str, new_email: str, update_committer: bool = True) → RewriteResult: Amend HEAD with a new author (and committer if update_committer). commit_id must resolve to HEAD.

filter_commits(author: str | None = None, message_contains: str | None = None) → RewriteResult: Drop commits matching author or message substring; merge commits are rejected.

remove_path(path_pattern: str) → RewriteResult: Purge a path (glob) from all commits reachable from HEAD; merge commits are rejected.

rebase_branch(branch: str, onto: str) → RewriteResult: Rebase a local branch onto a new base (pick-only). Returns old-to-new commit mapping in replay order.

squash_last(count: int, mode: str = 'squash', message: str | None = None) → RewriteResult: Squash the most recent commits into one. mode may be "squash" (concatenate messages) or "fixup" (keep oldest message). Raises if history is not linear across the requested range.

Functions (convenience)

pygitx.open_repo(path: str | os.PathLike[str]) → Repo: Open a git repository at path. Supports pathlib.Path and ~ expansion.

pygitx.summary(repo: Repo | str) → RepoSummary: Return a structured repository summary.

pygitx.refs_tui(repo: Repo | str, local: bool = True, remote: bool = False, tags: bool = True, max_width: int | None = None, color: bool = True) → str: Render branches/tags in a jj-style table (NAME/OID7/AGE/AUTHOR/SUMMARY). Set color=True for ANSI output.

pygitx.log_tui(repo: Repo | str, rev: str = 'HEAD', max_commits: int = 200, decorate: bool = True, graph: bool = True, max_width: int | None = None, color: bool = True) → str: Render a compact decorated log with optional ASCII graph. Set color=True for ANSI output.

pygitx.log_graph(repo: Repo | str, refs: list[str] | None = None, max_commits: int = 400, decorate: bool = True, max_width: int | None = None, color: bool = True) → str: Render a multi-branch decorated graph starting from refs (or all local branches). Set color=True for ANSI output.

Module-level convenience helpers are limited to open_repo, summary, refs_tui, log_tui, and log_graph. Prefer Repo methods for all other operations. .. py:function:: pygitx.rev_parse(repo: Repo | str, spec: str) -> str

Resolve a revision spec to a hex object id. Accepts typical git rev syntax (HEAD, HEAD~N, branches, tags, short/full oids).

pygitx.diff_stat(repo: Repo | str, a_spec: str, b_spec: str, paths: list[str] | None = None) → DiffStat: Compute diff stats between two revisions (optionally limited to the given paths).

pygitx.list_branches(repo: Repo | str, local: bool = True, remote: bool = False) → list[str]: List branch names (local/remote controlled by flags).

pygitx.list_tags(repo: Repo | str) → list[str]: List tag names.

pygitx.current_branch(repo: Repo | str) → str | None: Return the current branch name, or None if detached/unborn.

pygitx.merge_base(repo: Repo | str, a_spec: str, b_spec: str) → str | None: Compute merge base between two revisions.

pygitx.is_ancestor(repo: Repo | str, a_spec: str, b_spec: str) → bool: Return True if a_spec is an ancestor of b_spec.

pygitx.ahead_behind(repo: Repo | str, a_spec: str, b_spec: str) → tuple[int, int]: Return (ahead, behind) counts comparing a_spec to b_spec.

pygitx.reword(repo: Repo | str, commit_id: str, new_message: str) → RewriteResult: Reword an arbitrary commit on the current branch (linear history only).

pygitx.change_commit_message(repo: Repo | str, commit_id: str, new_message: str) → RewriteResult: Amend HEAD with a new message (rewrites history).

pygitx.rewrite_author(repo: Repo | str, commit_id: str, new_name: str, new_email: str, update_committer: bool = True) → RewriteResult: Amend HEAD with a new author (and committer if update_committer).

pygitx.filter_commits(repo: Repo | str, author: str | None = None, message_contains: str | None = None) → RewriteResult: Drop commits matching author or message substring; merge commits are rejected.

pygitx.remove_path(repo: Repo | str, path_pattern: str) → RewriteResult: Purge a path (glob) from all commits reachable from HEAD.

pygitx.rebase_branch(repo: Repo | str, branch: str, onto: str) → RewriteResult: Rebase a branch onto a new base (pick-only).

pygitx.squash_last(repo: Repo | str, count: int, mode: str = 'squash', message: str | None = None) → RewriteResult: Squash the most recent commits into one.

API Reference

Module

Classes

Functions (convenience)

Module 

Classes 