Weavatrix Git

weavatrix-git is a dependency-free, read-only Git storage engine written in safe Rust. Repository-analysis tools get direct, typed evidence without launching git, loading a C library, executing hooks, evaluating filters, or contacting a remote.

The crate is not a second Git client. Its contract is deterministic local intelligence: objects, refs, history, reachability, index state, and changes.

Why a separate crate?

A scanner discovers files. A code graph models relationships. This crate owns version-control evidence. Keeping that boundary independent lets any Rust application reuse Git intelligence without importing a larger product.

Supported contract

All public reads are in-process. Library code contains no subprocess fallback. Unsupported data returns a typed error rather than an approximate answer.

Usage

use weavatrix_git::{PathBloom, Repository};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let repository = Repository::open(".")?;
    let head = repository.resolve("HEAD")?;

    for id in repository.revwalk().push_head()?.take(100) {
        println!("{}", id?);
    }

    if repository.commit_maybe_changed_path(head, b"src/lib.rs")?
        == Some(PathBloom::DefinitelyNot)
    {
        println!("the commit definitely did not change src/lib.rs");
    }

    if let Some(objects) = repository.bitmap_reachable(head)? {
        println!("{} reachable objects", objects.len());
    }
    Ok(())
}

Custom stores use the same object contract:

use std::sync::Arc;
use weavatrix_git::{Limits, MemoryObjectBackend, Repository};

let backend = Arc::new(MemoryObjectBackend::default());
let repository =
    Repository::open_with_backends(".", Limits::default(), vec![backend])?;
# Ok::<_, weavatrix_git::GitError>(repository)

For cross-repository analysis, RepositorySet keeps object stores isolated and returns deterministic serial or parallel results:

use weavatrix_git::{HistoryOptions, RepositorySet};

let repositories = RepositorySet::open_parallel([
    ("service", "/code/service"),
    ("client", "/code/client"),
])?;
let histories =
    repositories.histories_from_parallel("HEAD", HistoryOptions::default())?;
let snapshots = repositories.snapshots_parallel("HEAD")?;
let timeline = repositories.timeline("HEAD", HistoryOptions::default())?;
let shared = repositories.shared_commits(HistoryOptions::default())?;
# Ok::<_, weavatrix_git::GitError>((histories, snapshots, timeline, shared))

The diagnostic CLI uses the library:

weavatrix-git [-C repository] head
weavatrix-git [-C repository] log [revision] [max-count]
weavatrix-git [-C repository] cat <object>
weavatrix-git [-C repository] diff <old-commit> <new-commit>

Architecture

Repository
  +-- refs + reflog
  +-- commit-graph chain + changed-path Bloom
  +-- index -> tracked status
  +-- custom ODB backends
  +-- object directories + alternates
        +-- loose object -> bounded zlib
        +-- MIDX -> pack -> bounded delta chain
        +-- pack/MIDX bitmap -> reachable object IDs

Limits bounds object bytes, cache bytes, delta/ref/tree depth, tree and index entries, reflog/history length, parent count, and bitmap expansion. The crate forbids unsafe Rust.

Correctness

The suite creates real Git repositories and verifies:

• loose and aggressively packed OFS/REF delta objects;
• SHA-1 and SHA-256 repositories;
• bare and linked-worktree layouts;
• classic MIDX lookup;
• multi-layer split commit-graphs and changed-path Bloom answers;
• pack and MIDX bitmap reachability against git rev-list --objects;
• index v2 and v4, reflog order, revwalk hide/reset, and tracked status;
• deterministic parallel and cross-repository results;
• immutable revision snapshots, merged timelines, and batch change sets;
• hostile format and configured-limit failures.

Current line coverage is 85.20%. CI runs Rust 1.88 on Linux, Windows, and macOS, Clippy with warnings denied, coverage, audit, docs, and package verification.

Performance

Release measurements on Windows, 2026-07-27:

Direct in-process comparison on the same packed 2,000-commit fixture:

On a separate 10,000-path index, warm reads measured 1.160/1.100/1.489 ms respectively; reopen measured 5.225/7.745/11.251 ms. The benchmark rotates engine order and proves exact history IDs, raw object bytes, and canonical index paths before timing. See BENCHMARKS.md.

On eight independent repositories with 8,000 selected commits, Weavatrix measured 5.667 ms serial history, 4.080 ms parallel history, 11.810 ms reopen, 4.148 ms shared-commit correlation, and 1.736 ms immutable manifests. It won all five p50 contracts against gix and libgit2; exact per-repository history order, shared locations, paths, and object IDs were proven first.

Position among alternatives

The deliberate remaining exclusions are pack index v1, reftable, incremental MIDX chains, split/sparse index extensions, shallow and replace-object semantics, revision-expression grammar, untracked/ignore/filter-aware status, submodule worktree status, network operations, and mutation.

Use Git, gix, or libgit2 for a complete client. Use this crate when bounded local evidence, a small audit surface, deterministic reads, and zero dependencies matter.

License

MIT