# Git repositories

> Clone, inspect, commit, pull, and push repositories in Flax sandboxes with temporary per-operation credentials for private repositories.

Every built-in Flax image includes Git, curl, and CA certificates. The Python and JavaScript SDKs
provide matching helpers for `clone`, `status`, `branches`, `checkout`, `add`, `commit`, `pull`,
and `push`.

Repositories created under `/workspace` are durable. Their files and `.git` metadata survive
stop/resume and are included in snapshots and forks. Running Git processes do not survive a stop.

## Public repositories

```python
sb.git.clone(
    "https://github.com/example/project.git",
    "/workspace/project",
    branch="main",
    depth=1,
)
```

```ts
await sb.git.clone(
  "https://github.com/example/project.git",
  "/workspace/project",
  { branch: "main", depth: 1 },
);
```

## Private repositories

Your application obtains a short-lived token from its Git provider, usually through a GitHub App
installation or OAuth flow. Pass that token to each network operation:

```python
token = get_short_lived_github_token()

sb.git.clone(
    "https://github.com/your-org/private-repo.git",
    "/workspace/repo",
    token=token,
)

sb.git.pull("/workspace/repo", token=token)
sb.git.push(
    "/workspace/repo",
    branch="agent/change",
    set_upstream=True,
    token=token,
)
```

```ts
const token = await getShortLivedGitHubToken();
const auth = { token };

await sb.git.clone(
  "https://github.com/your-org/private-repo.git",
  "/workspace/repo",
  { auth },
);
await sb.git.pull("/workspace/repo", { auth });
await sb.git.push("/workspace/repo", {
  branch: "agent/change",
  setUpstream: true,
  auth,
});
```

GitHub accepts the default username `x-access-token`. Other HTTPS Git providers can override it:

```python
sb.git.pull("/workspace/repo", username="oauth2", token=token)
```

```ts
await sb.git.pull("/workspace/repo", {
  auth: { username: "oauth2", token },
});
```

## Credential behavior

Credentials supplied through Git helpers:

- exist only for that synchronous `clone`, `pull`, or `push` operation;
- are not saved in the sandbox environment or command record;
- are not placed in the repository URL or `.git/config`;
- are not copied into snapshots or forks;
- use a temporary `GIT_ASKPASS` helper under `/tmp`, which is removed after the operation;
- are redacted if a runtime error or command output unexpectedly contains the token.

Use a clean HTTPS repository URL. Flax rejects credential-bearing URLs such as
`https://user:token@github.com/org/repo.git`.

Flax does not sign a sandbox into GitHub, store a long-lived provider token, or run an interactive
browser login. The product creating the sandbox owns the GitHub App or OAuth flow and supplies a
short-lived token when network access is needed.

## Commit identity

Set identity for one commit without writing global Git configuration:

```python
sb.git.add("/workspace/repo")
sb.git.commit(
    "Implement checkout validation",
    "/workspace/repo",
    author_name="Builder Agent",
    author_email="agent@example.com",
)
```

```ts
await sb.git.add("/workspace/repo");
await sb.git.commit("Implement checkout validation", "/workspace/repo", {
  authorName: "Builder Agent",
  authorEmail: "agent@example.com",
});
```

## CLI

The CLI deliberately has no plaintext `--token` flag because command-line arguments can be saved in
shell history and exposed through process listings. Read a token from an environment variable or
standard input:

```bash
flax git clone sbx_123 https://github.com/org/private.git /workspace/repo \
  --token-env GITHUB_TOKEN

printf '%s\n' "$GITHUB_TOKEN" | \
  flax git push sbx_123 --path /workspace/repo --branch agent/change \
  --set-upstream --token-stdin
```

Other commands:

```bash
flax git status sbx_123 /workspace/repo
flax git branches sbx_123 /workspace/repo
flax git checkout sbx_123 agent/change /workspace/repo -b
flax git add sbx_123 /workspace/repo --pathspec src
flax git commit sbx_123 --path /workspace/repo -m "Agent change" \
  --author-name "Builder Agent" --author-email agent@example.com
flax git pull sbx_123 --path /workspace/repo --token-env GITHUB_TOKEN
```

## Raw Git commands

You can still run any Git command through `sb.run()` or a session. Flax cannot provide credential
cleanup or command-history protection when a token is manually embedded in a command or URL. Use
the Git helpers for authenticated network operations.