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([
    ("service", "/code/service"),
    ("client", "/code/client"),
])?;
let histories = repositories.histories_parallel(HistoryOptions::default())?;
let shared = repositories.shared_commits(HistoryOptions::default())?;
# Ok::<_, weavatrix_git::GitError>((histories, 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;
• hostile format and configured-limit failures.

Current line coverage is 85.70%. 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:

These rows compare an in-process direct reader with a new CLI process. They are not claims against in-process gix or libgit2. Every harness checks output parity before recording time. See BENCHMARKS.md.

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