Atomic Transactions

Transactions collect multiple file changes and commit them as a single atomic operation. No partial commits — either all changes land or none do.

Quickstart

from githosted import Client

client = Client()
repo = client.repo("my-project")

with repo.transaction("Refactor auth module") as tx:
    tx.write("src/auth.py", new_auth_code)
    tx.write("tests/test_auth.py", new_test_code)
    tx.delete("src/old_auth.py")

API Reference

`repo.transaction(message, *, ref, expected_head)`

Start a transaction. Returns a context manager that stages changes and commits on exit.

with repo.transaction("Add feature") as tx:
    tx.write("src/feature.py", code)
    tx.write("tests/test_feature.py", tests)

Transaction options

with repo.transaction(
    "Fix bug on feature branch",
    ref="feature/fix",
    expected_head=file.head_sha,
) as tx:
    tx.write("src/main.py", fixed_code)

`tx.write(path, content)`

Stage a file write. Content can be str or bytes.

`tx.delete(path)`

Stage a file deletion.

Common Patterns

Read-modify-write with concurrency safety

import json

file = repo.read("package.json")
pkg = json.loads(file.content)
pkg["version"] = "2.0.0"

with repo.transaction(
    "Bump version to 2.0.0",
    expected_head=file.head_sha,
) as tx:
    tx.write("package.json", json.dumps(pkg, indent=2))
    tx.write("CHANGELOG.md", changelog_entry)

Agent save points

Agents can use transactions to create atomic “save points” of their work:

changes = generate_code(prompt, existing_files)

with repo.transaction(f"Agent: {prompt[:60]}") as tx:
    for path, content in changes.items():
        tx.write(path, content)

Error Handling

If expected_head is set and the branch has moved, the transaction throws a StaleHeadError. See Error Handling.