Skip to main content

gitd for Python

A client for gitd: instant, secretless git checkouts for agent sandboxes. Your agents work in their own copy and publish a branch; they never see your token.

pip install gitd-client

It is imported as gitd. Up to 0.13.0 it was published as gitd; from 0.14.0 it is gitd-client, the name every gitd client has.

from gitd import Gitd, GitdError

with Gitd() as gitd:                      # $GITD_SOCKET, then /run/gitd/gitd.sock
    workspace = gitd.prepare("https://github.com/acme/web", "/var/lib/gitd/workspaces/agent-1")
    print(workspace.path, workspace.commit, workspace.strategy)

    # … the agent works in workspace.path with plain git, and commits …

    published = gitd.publish(workspace.path, "agents/fix-login")
    gitd.remove(workspace.path)

No call takes a credential: gitd reads and publishes with the ones it keeps.

Method What it does
prepare(url, path, *, branch, commit, submodules, full_history, strategy, on_progress) A workspace of a repository at a path under gitd's roots
update(path, *, branch, submodules, on_progress) To the tip of its branch, or of the branch given
checkout(path, commit, *, submodules, on_progress) To a commit, as a rollback does
describe(path) Its repository, commit, branch, uncommitted changes and submodules
publish(path, branch, *, requested_by, pull_request, provenance, sandbox, update) Its commits pushed to a new branch, or with update an earlier publish's branch moved forward; its pull request opened or updated
remove(path) Deleted; its pool stays
probe(url) Whether it can be read, its default branch and branches
info() Which gitd answers, and how it makes workspaces here and why
audit(*, since, url, limit) Every publish, done or refused, newest first
from gitd import PullRequestOptions

published = gitd.publish(
    workspace.path, "agents/fix-login", update=True,
    pull_request=PullRequestOptions(open=True, submodules=True, title="Fix the login", body="…"),
)
print(published.pull_request.url, published.pull_request.updated)
for submodule in published.submodule_pull_requests:   # merged first, with a merge commit
    print(submodule.path, submodule.pull_request or submodule.refused)

A refusal raises GitdError, with reason (AUTH_REQUIRED, NOT_FOUND, PATH_REFUSED, BRANCH_REFUSED, BUSY, …) and said, what git said. Decide from the reason, never from the message.

examples/agent.py is an agent's whole round trip.

Layout

Path What it is
src/gitd/client.py Gitd, the client
src/gitd/models.py What gitd answers, as dataclasses
src/gitd/errors.py GitdError
src/gitd/timestamps.py Between the contract's timestamps and datetime
src/gitd/connection.py The channel to the socket, and how calls are made
src/gitd/methods.py The gitd methods called, by their gRPC path
src/gitd/messages.py The messages of the contract the client uses
src/gitd/contract.py Reads the contract at run time, with protobuf's public API
src/gitd/contract.json The contract, built from proto/gitd/v1/gitd.proto by make generate

No code is generated: the client reads gitd's contract when it starts.

Python 3.11 or later, on Linux, macOS and Windows. Apache-2.0.

Metadata

Release files for gitd-client 0.14.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for gitd-client 0.14.0
File Size Uploaded Provenance Actions
gitd_client-0.14.0.tar.gz 26.2 kB With provenance Details for gitd_client-0.14.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for gitd-client 0.14.0
File Interpreter ABI Platform Actions
gitd_client-0.14.0-py3-none-any.whl Python 3 none any Details for gitd_client-0.14.0-py3-none-any.whl

Total release size: 58.7 kB

Release files / gitd_client-0.14.0.tar.gz

Download URL gitd_client-0.14.0.tar.gz
Size 26.2 kB
Tags Source
SHA-256 checksum
How to use checksums
98ab14ab4cf2ef29d4bad56434152e2671c6c3909d8a258441c85ef25077020d
BLAKE2b-256 checksum
How to use checksums
d246e1c7ee41e541eff046ceac3d260a475cdb8f1911d17f9d0628c824f7af42
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

Release files / gitd_client-0.14.0-py3-none-any.whl

Download URL gitd_client-0.14.0-py3-none-any.whl
Size 32.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
18ed6cdf4d22495d5f1162b61d0697d3377d5784c5c40b094125dfc88dafb3bd
BLAKE2b-256 checksum
How to use checksums
f85b030c91eebed2c9ef65d99f9993f4fbffc0ec097741c217635f9acc8a104e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

Security for gitd-client 0.14.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for gitd_client-0.14.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page