grit-lib

Core library for Grit, a from-scratch reimplementation of Git in Rust.

grit-lib provides the low-level building blocks for working with Git repositories: object storage, index manipulation, refs, diffing, merge, revision walking, configuration, and more. It is the engine behind the grit CLI but is designed to be usable as a standalone library for anyone who wants to read, write, or inspect Git repositories from Rust without shelling out to git.

Design philosophy

• Correctness first. Behavior is validated against Git's own test suite. Edge cases (empty trees, encoding quirks, unusual ref names) are handled the way Git handles them.
• No unsafe code. The workspace forbids unsafe — all I/O goes through safe Rust and standard-library abstractions.
• Minimal dependencies. The library leans on a small set of widely-used crates (sha1, flate2, hex, similar, regex, time, tempfile, thiserror) and nothing else.
• Granular errors. Every module returns typed errors via thiserror so callers can match on exactly what went wrong.

Quick start

Add the dependency:

[dependencies]
grit-lib = "0.1"

Open a repository and read an object

use grit_lib::repo::Repository;

let repo = Repository::discover(".")?;
let head = grit_lib::state::resolve_head(&repo.git_dir)?;

if let Some(oid) = head.oid() {
    let obj = repo.odb.read(oid)?;
    println!("{} {} bytes", obj.kind, obj.data.len());
}

Walk the commit graph

use grit_lib::rev_list::{rev_list, RevListOptions, OutputMode};

let mut opts = RevListOptions::default();
opts.output = OutputMode::OidOnly;
let result = rev_list(&repo.odb, &repo.git_dir, &include, &exclude, &opts)?;
for oid in &result.oids {
    println!("{}", oid.to_hex());
}

Diff two trees

use grit_lib::diff::{diff_trees, DiffEntry};

let entries: Vec<DiffEntry> = diff_trees(&repo.odb, Some(old_tree), Some(new_tree))?;
for e in &entries {
    println!("{} {}", e.status, e.new_path.as_deref().or(e.old_path.as_deref()).unwrap());
}

Read and write the index

use grit_lib::index::Index;

let mut index = Index::load(&repo.index_path())?;
index.add_or_replace(entry);
index.sort();
index.write(&repo.index_path())?;

Module overview

License

MIT