API reference

GitBugRepo 

class ezgb.GitBugRepo(repo_path)[source]

High-level interface to a git-bug repository.

Reads bug data directly from git objects for speed. Writes go through the git bug CLI to maintain Lamport clock and DAG consistency.

Usage:

repo = GitBugRepo('/path/to/repo')
for bug in repo.list_bugs(status=Status.OPEN):
    print(bug.title)

Parameters:: repo_path (str)

list_bugs(*, status=None, label=None, since=None)[source]

List all bugs, optionally filtered by status, label, and/or modification time.

since accepts a unix timestamp (int), a datetime, or a string in ISO-8601 / YYYYMMDDHHMMSS format. Only bugs whose tip commit is newer than this value are returned.

Parameters:

status (Status | None)
label (str | None)
since (str | datetime | int | None)

Return type:

list[Bug]

iter_bugs(*, status=None, label=None, since=None)[source]

Lazily iterate over bugs, yielding one at a time.

Accepts the same filters as list_bugs() but avoids building all snapshots up front, which saves memory on large repositories.

Parameters:

status (Status | None)
label (str | None)
since (str | datetime | int | None)

Return type:

Iterator[Bug]

list_bug_summaries(*, status=None, label=None, since=None)[source]

List lightweight bug summaries, optionally filtered.

Uses the git-bug CLI cache when available (~100ms for hundreds of bugs). Falls back to native git object reads when the CLI is not installed or the cache is empty.

Parameters:

status (Status | None)
label (str | None)
since (str | datetime | int | None)

Return type:

list[BugSummary]

iter_bug_summaries(*, status=None, label=None, since=None)[source]

Lazily iterate over bug summaries.

Accepts the same filters as list_bug_summaries().

Parameters:

status (Status | None)
label (str | None)
since (str | datetime | int | None)

Return type:

Iterator[BugSummary]

get_bug(bid)[source]

Get a single bug by ID (full or abbreviated).

Parameters:: bid (str)
Return type:: Bug

get_attachment(blob_hash)[source]

Read a file attachment by its blob hash.

Blob hashes are found in Comment.attachment_ids.

Parameters:: blob_hash (str)
Return type:: bytes

search(query)[source]

Search bugs using the git-bug CLI query language.

Delegates to git bug -f json <query> and reconstructs Bug objects from the results.

Parameters:: query (str)
Return type:: list[Bug]

list_identities()[source]

List all known identities.

Return type:: list[Identity]

resolve_bug_id(bid)[source]

Resolve an abbreviated bug ID to the full 64-char ID.

Parameters:: bid (str)
Return type:: str

create_bug(title, body)[source]

Create a new bug and return its snapshot.

Parameters:

title (str)
body (str)

Return type:

Bug

add_comment(bid, text)[source]

Add a comment to a bug and return the new Comment.

Parameters:

bid (str)
text (str)

Return type:

Comment

edit_comment(bid, comment_id, text)[source]

Edit a comment’s text.

Parameters:

bid (str)
comment_id (str)
text (str)

Return type:

None

set_status(bid, status)[source]

Set a bug’s status to open or closed.

Parameters:

bid (str)
status (Status)

Return type:

None

set_title(bid, title)[source]

Edit a bug’s title.

Parameters:

bid (str)
title (str)

Return type:

None

add_label(bid, label)[source]

Add a label to a bug.

Parameters:

bid (str)
label (str)

Return type:

None

remove_label(bid, label)[source]

Remove a label from a bug.

Parameters:

bid (str)
label (str)

Return type:

None

remove_bug(bid)[source]

Permanently delete a bug. This is irreversible.

Parameters:: bid (str)
Return type:: None

push(remote='origin')[source]

Push bugs and identities to a remote.

Returns (returncode, stdout, stderr).

Parameters:: remote (str)
Return type:: tuple[int, str, str]

pull(remote='origin')[source]

Pull bugs and identities from a remote and merge.

Returns (returncode, stdout, stderr). Caches are invalidated automatically after pull.

Parameters:: remote (str)
Return type:: tuple[int, str, str]

invalidate(bid=None)[source]

Clear cached data.

If bid is given, only that bug is evicted. Otherwise all caches are cleared.

Parameters:: bid (str | None)
Return type:: None

Data classes 

Bug 

class ezgb.Bug(id, title, status, creator, created_at, labels, comments, metadata=<factory>)[source]

A git-bug bug snapshot reconstructed from operations.

Parameters:

id (str)
title (str)
status (Status)
creator (Identity)
created_at (datetime)
labels (set[str])
comments (list[Comment])
metadata (dict[str, str])

id: str

title: str

status: Status

creator: Identity

created_at: datetime

labels: set[str]

comments: list[Comment]

metadata: dict[str, str]

class ezgb.BugSummary(id, title, status, creator_id, created_at, labels, comment_count, author_name='', edited_at=datetime.datetime(1, 1, 1, 0, 0, tzinfo=datetime.timezone.utc))[source]

Lightweight bug snapshot for list views.

Contains only the fields needed for display in listings. Identity resolution is deferred – creator_id holds the raw identity hash string rather than a resolved Identity object.

Both the git-bug CLI cache and native git-object reads populate author_name (the creator’s resolved display name) and edited_at (the last-activity time). author_name may fall back to the raw identity hash if the identity cannot be resolved.

Parameters: