Library guide / ObjectsMarkdown

Objects

ObjectId, ObjectKind, and reading or writing blobs, trees, and commits through Odb.

Git stores four object kinds grit-lib exposes as ObjectKind. Every object is named by an ObjectId (SHA-1 by default). The Odb on Repository reads loose objects and packed storage transparently.

Writing

Odb::write takes a kind and payload bytes, stores a loose object under objects/, and returns the id. Tree and commit bodies must already be in Git’s text format; use parse_tree and parse_commit when reading them back.

Odb::hash (or HashAlgo::hash_object) computes an id without writing—useful for dry runs and tests. The algorithm follows the repository’s configured object format (SHA-1 or SHA-256).

Reading

Odb::read returns an Object with kind and uncompressed data. Packed and loose objects share the same API.

When you only need type and size (for example listing objects without loading blob bodies), use Odb::read_info (see read_info on Odb). It returns ObjectInfo and avoids inflating full payloads for loose objects and non-delta pack entries; delta chains are resolved from headers and delta size varints only.

Pack read caching

Odb owns a repository-scoped PackStore: pack directory listings, parsed .idx files, pack bytes, MIDX layers, and the delta-base LRU. Cloned Odb handles share the same store; alternate object directories get separate stores on the parent Odb.

After repack, garbage collection, or installing a pack with install_pack_bytes, call Odb::invalidate_packs so the next read rescans objects/pack/. If another Odb in the same process still holds a stale listing, a lookup miss retriggers directory reprepare when the pack folder’s mtime changes.

For batch reads (cat-file --batch, --batch-all-objects), wrap the loop in Odb::with_pack_read_context so pack indexes, mmap-backed pack bytes, and the delta-base LRU stay on one thread-local context instead of reinstalling it per object. Odb::read detects an active matching context and skips nested setup.

When iterating a pack in offset order (unordered --batch-all-objects), prefer read_object_from_pack_at_offset with the entry offset from PackIndex so the read path does not repeat index lookup by OID.

Pack deltas (encoding)

When building new pack deltas (as opposed to reusing on-disk zlib), grit-lib indexes the base blob with DeltaIndex and encodes targets with a rolling fingerprint matcher. Reuse one index across many targets in a pack-objects window; encode on that index accepts an optional max_size cap (zero means no limit). An empty target yields a valid delta (header varints only). encode_delta is a convenience wrapper for one-off base/target pairs.

//! Write a blob, tree, and commit through [`grit_lib::odb::Odb`], then read them back. //! //! Source for the library guide "Objects" page (included in the docs site). use grit_lib::objects::{ parse_commit, parse_tree, serialize_commit, serialize_tree, CommitData, ObjectKind, TreeEntry, }; use grit_lib::repo::{init_repository, Repository}; use std::path::{Path, PathBuf}; fn write_demo_objects( repo: &Repository, ) -> Result< ( grit_lib::objects::ObjectId, grit_lib::objects::ObjectId, grit_lib::objects::ObjectId, ), grit_lib::error::Error, > { let blob_data = b"hello from the library guide\n"; let blob_oid = repo.odb.write(ObjectKind::Blob, blob_data)?; let tree_entries = vec![TreeEntry { mode: 0o100644, name: b"README".to_vec(), oid: blob_oid, }]; let tree_oid = repo .odb .write(ObjectKind::Tree, &serialize_tree(&tree_entries))?; let commit = CommitData { tree: tree_oid, parents: Vec::new(), author: "Ada Lovelace <ada@example.com> 0 +0000".to_owned(), committer: "Ada Lovelace <ada@example.com> 0 +0000".to_owned(), author_raw: Vec::new(), committer_raw: Vec::new(), encoding: None, message: "Library guide objects example\n".to_owned(), raw_message: None, extra_headers: Vec::new(), }; let commit_oid = repo .odb .write(ObjectKind::Commit, &serialize_commit(&commit))?; let tree_obj = repo.odb.read(&tree_oid)?; let entries = parse_tree(&tree_obj.data)?; assert_eq!(entries[0].oid, blob_oid); let commit_obj = repo.odb.read(&commit_oid)?; let parsed = parse_commit(&commit_obj.data)?; assert_eq!(parsed.tree, tree_oid); Ok((blob_oid, tree_oid, commit_oid)) } fn open_repo(root: &Path) -> Result<Repository, grit_lib::error::Error> { let git_dir = if root.join(".git").is_dir() { root.join(".git") } else { root.to_path_buf() }; let work_tree = if root.join(".git").is_dir() { Some(root) } else { None }; Repository::open(&git_dir, work_tree) } fn main() -> Result<(), grit_lib::error::Error> { let repo = if let Some(root) = std::env::args().nth(1).map(PathBuf::from) { open_repo(&root)? } else { let temp = tempfile::tempdir().map_err(grit_lib::error::Error::Io)?; init_repository( temp.path(), false, "main", None, grit_lib::RefStorageFormat::Files, )?; open_repo(temp.path())? }; let (blob_oid, tree_oid, commit_oid) = write_demo_objects(&repo)?; println!("{commit_oid}"); println!("blob={blob_oid} tree={tree_oid}"); Ok(()) }