hanna/arc

refactor: switch storage format from MessagePack to bincode

- 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

2026-02-10 21:03:53 +00:00

2.9 KiB

Raw Permalink Blame History

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.

2.9 KiB Raw Permalink Blame History