# Git Bridge

Arc uses an internal git bridge to interoperate with git remotes. Since Arc uses its own delta-based storage format (ZSTD-compressed bincode), it maintains a shadow bare git repository to translate between formats when communicating with git servers.

## Shadow Repository

- Located at `.arc/git/` — a bare git repository created automatically on first use.
- A bidirectional mapping between arc commit IDs and git OIDs is stored in `.arc/git-map.yml`.
- The map has two fields: `arc_to_git` and `git_to_arc`, both string-to-string mappings.

## Commit Conversion

**Arc → Git:** The bridge materializes the full file tree at each arc commit, writes it as a git tree object, and creates a git commit with the same message, author, and timestamp. Parents are recursively converted. Cached mappings are reused.

**Git → Arc:** The bridge reads the git tree, computes deltas against the parent's tree using Arc's `detect_changes`, and creates arc `CommitObject` entries. Author info and timestamps are preserved from the git commit.

## Authentication

- SSH authentication is attempted first via the SSH agent, then by scanning `~/.ssh/` for key files (`id_ed25519`, `id_rsa`, `id_ecdsa`).
- Interactive/password authentication is not supported.
- Up to 4 authentication attempts are made before failing.

## Commands

### Push (`arc push [-r remote]`)

- Converts all arc commits on the current bookmark to git commits.
- Pushes the current bookmark as a git branch to the remote.
- Only pushes the active bookmark's branch.
- Uses fast-forward only; diverged histories produce an error.
- Default remote is `origin` (configurable via `default.remote`).

### Pull (`arc pull [-r remote]`)

- Fetches from the remote into the shadow git repo.
- Converts new git commits to arc commits.
- Fast-forward only — if the local bookmark has diverged, an error is returned.
- Updates the bookmark pointer and worktree.

### Clone (`arc clone [-b branch] <url> [path]`)

- Clones the git remote into a new arc repository.
- Imports all branches as bookmarks and tags.
- Checks out the specified branch (or the remote HEAD, or `main` by default).
- Writes the full worktree after import.

### Migrate (`arc migrate`)

- Converts an existing git repository (in the current directory) to an arc repository.
- Creates `.arc/` alongside the existing `.git/`.
- Imports all `refs/heads/*` as bookmarks and `refs/tags/*` as tags.
- Preserves remotes from the git config.
- Sets HEAD to the same branch as the git repo's HEAD.

### Sync (`arc sync [-p]`)

- Ensures the shadow git repo mirrors all arc bookmarks and tags.
- Converts any new arc commits to git commits and updates git refs.
- With `-p` (`--push`), also pushes all refs to the default remote.

## Remotes

- Stored in `.arc/remotes.yml` as a YAML map of name → URL.
- Managed with `arc remote add|rm|list`.
- When pushing to git, bookmarks become git branches and tags become git tags.