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

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)`	Its commits pushed to a new branch
`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

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. Apache-2.0.

Metadata

Release files for gitd 0.9.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 0.9.0
File	Size	Uploaded
gitd-0.9.0.tar.gz	25.3 kB	Oct 18, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for gitd 0.9.0
File	Interpreter	ABI	Platform	Reset
gitd-0.9.0-py3-none-any.whl 31.5 kB Oct 18, 2026	Python 3	none	any	Details

Total release size: 56.9 kB

Release files / gitd-0.9.0.tar.gz

Download URL	gitd-0.9.0.tar.gz
Size	25.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`5d649a725ea71eaec4f53352b0aa5d1783413f3ffff45c88429a77b676de4ed6`
BLAKE2b-256 checksum How to use checksums	`f441f6b841c26b2fe98f9b1e448cac45073115ff500b75c49d19b3fd36f81d21`
Upload date	Oct 18, 2026
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.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/dooservice/gitd
Publishing commit: github.com/dooservice/gitd/tree/008d94ace8a865be13e285955c08509fd75626db

Workflow

Publishing configuration: github.com/dooservice/gitd/blob/008d94ace8a865be13e285955c08509fd75626db/.github/workflows/sdks.yml
Publishing logs: github.com/dooservice/gitd/actions/runs/39097097230/attempts/1

Artifact

Subject: gitd-0.9.0.tar.gz
SHA-256 checksum: 5d649a725ea71eaec4f53352b0aa5d1783413f3ffff45c88429a77b676de4ed6 Verifying attestations

Release files / gitd-0.9.0-py3-none-any.whl

Download URL	gitd-0.9.0-py3-none-any.whl
Size	31.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`e6ccfbea8c412cffbc473d61e835eee4096f63a929497b7c62e3ebb64942608d`
BLAKE2b-256 checksum How to use checksums	`378cb120d7eaf62e2632a5166c8bff5e8992f38e5b9dcdef085d8665e1fbfc13`
Upload date	Oct 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/dooservice/gitd
Publishing commit: github.com/dooservice/gitd/tree/008d94ace8a865be13e285955c08509fd75626db

Workflow

Publishing configuration: github.com/dooservice/gitd/blob/008d94ace8a865be13e285955c08509fd75626db/.github/workflows/sdks.yml
Publishing logs: github.com/dooservice/gitd/actions/runs/39097097230/attempts/1

Artifact

Subject: gitd-0.9.0-py3-none-any.whl
SHA-256 checksum: e6ccfbea8c412cffbc473d61e835eee4096f63a929497b7c62e3ebb64942608d Verifying attestations