> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wrenn.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Git Operations Inside Wrenn Capsules

> Use capsule.git to run Git operations inside a capsule — init, clone, commit, push, pull, and branch management with credential support.

`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

```python theme={null}
capsule.git.init("/app", initial_branch="main")
```

## Configure user identity

Set a user name and email before making commits. By default, `configure_user` writes to the global git config inside the capsule:

```python theme={null}
capsule.git.configure_user("Alice", "alice@example.com", cwd="/app")
```

## Stage and commit

```python theme={null}
# 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:

```python theme={null}
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)
```

Each entry in `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

```python theme={null}
# 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:

```python theme={null}
capsule.git.clone(
    "https://github.com/org/repo.git",
    username="user",
    password="ghp_token",
    cwd="/app",
)
```

<Warning>
  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.
</Warning>

## Push and pull

Credentials are temporarily embedded in the remote URL for the duration of the operation, then restored to their original value:

```python theme={null}
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

```python theme={null}
# 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`:

```python theme={null}
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)
```

<Note>
  `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.
</Note>