capsule.git gives you a full Git interface inside a running capsule. Every operation executes the real git binary inside the microVM — there is no reimplementation. This means you get full Git fidelity: all flags, all error messages, and all standard behaviors.
Initialize a repository
capsule.git.init("/app", initial_branch="main")
configure_user writes to the global git config inside the capsule:
Stage and commit
# Stage all changes
capsule.git.add(all=True, cwd="/app")
# Create a commit
capsule.git.commit("initial commit", cwd="/app")
Check repository status
status() returns a GitStatus object with the current branch, a clean flag, and a list of changed files:
status = capsule.git.status(cwd="/app")
print(status.branch) # "main"
print(status.is_clean) # True or False
for f in status.files:
print(f.path, f.index_status, f.work_tree_status)
status.files is a FileStatus with three fields:
| Field | Type | Description |
|---|
path | str | Path to the file, relative to the repo root |
index_status | str | Single-character status code for the index (staging area) |
work_tree_status | str | Single-character status code for the working tree |
Branch management
# List local branches
branches = capsule.git.branches(cwd="/app")
# Create and check out a new branch
capsule.git.create_branch("feature", cwd="/app")
# Switch to an existing branch
capsule.git.checkout_branch("main", cwd="/app")
# Delete a branch
capsule.git.delete_branch("feature", cwd="/app")
Clone with authentication
Pass username and password to authenticate against a private repository. After a successful clone, Wrenn strips the credentials from the remote URL so they are not persisted in the capsule’s git config:
capsule.git.clone(
"https://github.com/org/repo.git",
username="user",
password="ghp_token",
cwd="/app",
)
Use token-based authentication (GitHub personal access tokens, GitLab project tokens, etc.) rather than account passwords. Account passwords are unlikely to work with modern Git hosts that enforce OAuth or two-factor authentication.
Push and pull
Credentials are temporarily embedded in the remote URL for the duration of the operation, then restored to their original value:
capsule.git.push("origin", "main", username="user", password="ghp_token", cwd="/app")
capsule.git.pull("origin", "main", username="user", password="ghp_token", cwd="/app")
Configuration and remotes
# Set and get arbitrary git config values
capsule.git.set_config("core.autocrlf", "false", cwd="/app")
value = capsule.git.get_config("user.name", cwd="/app") # str | None
# Add a remote and read its URL
capsule.git.remote_add("upstream", "https://github.com/org/repo.git", cwd="/app")
url = capsule.git.remote_get("origin", cwd="/app") # str | None
Error handling
All git methods raise GitCommandError on a non-zero exit code, or GitAuthError when the remote rejects authentication. Both inherit from GitError and expose .stderr and .exit_code:
from wrenn import GitCommandError, GitAuthError
try:
capsule.git.push("origin", "main", username="user", password="wrong", cwd="/app")
except GitAuthError as e:
print(e.stderr) # raw stderr from git
print(e.exit_code) # e.g. 128
except GitCommandError as e:
print(e.message)
GitError and its subclasses are not part of the WrennError hierarchy — they originate from a process exit code, not an HTTP response from the Wrenn API.
