Library guide / Object storesMarkdown

Object stores

Pluggable ObjectStore backends, OdbBuilder, and the odb_conformance test suite.

By default Repository opens a files-backed Odb (loose objects, packs, and optional MIDX). Embedders can swap the primary store or add read-only layers with OdbBuilder and Repository::open_with_odb.

Traits

Trait	Role
`ObjectStore`	Read, metadata, streaming, enumeration
`WritableObjectStore`	Insert objects (idempotent writes)

Built-in backends live under grit_lib::odb::store (LooseStore, FilesSource, MemoryStore, CompositeStore, and others).

Lookup order

For a given Odb handle:

In-memory overlay (when enabled for merge-tree-style operations)
Primary store — files source by default, or your custom WritableObjectStore
Extra read sources from OdbBuilder::push_read_source
Alternate object directories when OdbBuilder::alternates is true (info/alternates, environment alternates, submodule object dirs)

Building a custom repository

use std::sync::Arc;

use grit_lib::environment::RepositoryOptions;
use grit_lib::objects::{HashAlgo, ObjectKind};
use grit_lib::odb::store::MemoryStore;
use grit_lib::odb::OdbBuilder;
use grit_lib::repo::{init_repository, Repository};

let dir = tempfile::tempdir()?;
init_repository(dir.path(), false, "main", None, "files")?;
let git_dir = dir.path().join(".git");
let store = Arc::new(MemoryStore::new(HashAlgo::Sha1));
let repo = Repository::open_with_odb(
    &RepositoryOptions::empty(),
    &git_dir,
    Some(dir.path()),
    OdbBuilder::files(git_dir.join("objects"))
        .primary(store)
        .alternates(false),
)?;
let _blob = repo.odb.write(ObjectKind::Blob, b"hello")?;

Filesystem-only maintenance (Odb::gc, Odb::write_commit_graph, Odb::pack_store, pack install, MIDX write) returns Error::UnsupportedObjectStore when the primary is not the default files backend. Use Odb::files_objects_dir when you need the on-disk objects/ path only for files-backed repos.

Conformance tests

The workspace crate grit_test_support::odb_conformance provides shared read/write suites. Run them from an integration test in your crate (see grit-lib/tests/odb_conformance_memory.rs) to validate a custom backend before wiring it through OdbBuilder.

//! Custom append-only object store wired through [`OdbBuilder::primary`]. //! //! Writes a small commit graph in the KV store, walks history with [`rev_list`], //! then exports objects as loose files for interoperability with system Git. use std::env; use std::path::PathBuf; use grit_examples::packfile_kv; fn main() -> grit_lib::error::Result<()> { let (root, _tmpdir) = match env::args().nth(1) { Some(path) => (PathBuf::from(path), None), None => { let dir = tempfile::tempdir().map_err(grit_lib::error::Error::Io)?; let root = dir.path().to_path_buf(); (root, Some(dir)) } }; let log = packfile_kv::run_custom_object_store_demo(&root)?; for oid in log { println!("{oid}"); } Ok(()) }

//! SQLite object store wired through [`OdbBuilder::primary`]. //! //! Writes a small commit graph in SQLite, walks history with [`rev_list`], //! then exports objects as loose files for interoperability with system Git. use std::env; use std::path::PathBuf; use grit_examples::sqlite_odb; fn main() -> grit_lib::error::Result<()> { let (root, _tmpdir) = match env::args().nth(1) { Some(path) => (PathBuf::from(path), None), None => { let dir = tempfile::tempdir().map_err(grit_lib::error::Error::Io)?; let root = dir.path().to_path_buf(); (root, Some(dir)) } }; let log = sqlite_odb::run_sqlite_object_store_demo(&root)?; for oid in log { println!("{oid}"); } Ok(()) }