arc/docs/architecture.md

Architecture

Arc is a version control system with its own data model, storage format, and a git bridge for interoperability.

Repository Layout

An arc repository keeps all state in an .arc/ directory at the worktree root:

Path	Format	Purpose
HEAD	YAML	Current state — one of three variants: unborn (no commits yet; has bookmark), attached (on a bookmark; has bookmark + commit), or detached (raw commit; has commit).
config.yml	YAML	Local repository configuration.
commits/<id>.zst	Zstandard-compressed bincode	Commit objects. Each file contains a CommitObject that bundles a Commit and its Delta.
bookmarks/<name>.yml	YAML	One file per bookmark. Contains a RefTarget with an optional commit field.
tags/<name>.yml	YAML	Same format as bookmarks.
stashes/state.yml	YAML	Tracks the active stash.
stashes/named/<name>.yml	YAML	Per-stash state files.
remotes.yml	YAML	Map of remote names to URLs.
git/	Bare git repo	Shadow repository used by the git bridge.
git-map.yml	YAML	Bidirectional mapping between arc commit IDs and git OIDs.

Data Model (src/model.rs)

CommitId and DeltaId are newtype wrappers around String, holding SHA-256 hex hashes.

Commit — id, parents (Vec), delta (DeltaId), message, author (optional Signature), timestamp (i64 unix), ssh_signature (optional PEM string).

Delta — id, base (optional parent CommitId), changes (Vec of FileChange).

FileChange — path plus a kind: Add, Modify, Delete, or Rename.

FileContentDelta — either Full { bytes } (complete snapshot) or Patch { format, data } (incremental).

Head — enum with variants Unborn, Attached, and Detached.

Storage (src/store.rs)

CommitObject bundles a Commit and its Delta into a single unit that is serialized with bincode, then compressed with Zstandard at level 3. Files are written atomically (write to .tmp, then rename). IDs are computed by SHA-256 hashing the bincode-serialized content-addressable data.

Tracking (src/tracking.rs)

FileTree is a BTreeMap<String, Vec<u8>> mapping relative paths to file content.

• scan_worktree — recursively walks the working directory, respecting ignore rules and skipping .arc/ and .git/.
• materialize_committed_tree — rebuilds the full file tree by replaying the linear delta chain from the root commit.
• detect_changes — compares the committed tree against the worktree to produce a list of FileChange entries (adds, modifies, deletes).

Ignore System (src/ignore.rs)

Reads .arcignore first, falling back to .ignore. Always ignores .arc/ and .git/.

• * and ? glob wildcards.
• ! prefix for negation.
• Patterns without / match any path component; patterns with / match the full relative path.
• Patterns ending with / match directories only.

Git Bridge (src/bridge.rs)

Maintains a shadow bare git repository under .arc/git/.

GitMap provides bidirectional mapping (arc_to_git / git_to_arc) persisted in .arc/git-map.yml.

• arc_to_git recursively converts arc commits to git commits, materializing file trees as git tree objects.
• git_to_arc does the reverse, computing deltas from git tree diffs.
• SSH authentication via agent or key files (~/.ssh/id_ed25519, id_rsa, id_ecdsa).

Merge (src/merge.rs)

Full three-way merge with line-level merging for text files using Myers diff. Conflicts are marked with <<<<<<< ours / ======= / >>>>>>> theirs. Binary files fall back to keeping the "ours" version on conflict.

Signing (src/signing.rs)

Optional SSH key signing using the ssh-key crate. Signs with SHA-512 under the arc namespace. Verification extracts the public key from the signature itself. Supports ~ expansion in key paths.

Source Modules

Module	Responsibility
main.rs	Entry point, macro definitions
cli.rs	Clap-based CLI parsing and command dispatch
model.rs	Core data types
store.rs	Commit/delta serialization and content-addressing
tracking.rs	Worktree scanning, change detection, commit logic
repo.rs	Repository init/open/discover, path validation
config.rs	YAML config loading, merging (local-first), effective config
refs.rs	Bookmark/tag CRUD, switch, worktree write/clean
bridge.rs	Git bridge (shadow repo, push, pull, clone, migrate, sync)
diff.rs	Unified diff rendering
inspect.rs	Log, show, history (blame), Myers diff
merge.rs	Three-way merge
modify.rs	Reset, revert, merge command, graft
resolve.rs	Target/range resolution (bookmarks, tags, prefixes, HEAD)
ignore.rs	Ignore file parsing and matching
signing.rs	SSH commit signing and verification
stash.rs	Named stash system
remote.rs	Remote management (remotes.yml)
error.rs	Error types
ui.rs	Colored output formatting