hanna
a6b1a027c8
- Replace rmp-serde with bincode 1.x in Cargo.toml - Update store.rs serialization/deserialization and ID hashing - Rename model.rs helpers from to_msgpack/from_msgpack to to_bytes/from_bytes - Consolidate MsgPack/MsgPackDecode error variants into single Bincode variant - Remove skip_serializing_if on ssh_signature (incompatible with bincode) - Update all documentation to reflect bincode storage format
65 lines
2.9 KiB
Markdown
65 lines
2.9 KiB
Markdown
# 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.
|