Struct Objects 

pub struct Objects { /* private fields */ }

Reads loose objects and validated, pinned local pack/index files.

Common operations

Use Self::read for an object payload and Self::refresh to discover newly published packs without replacing a valid reader on failure. Self::compare_trees reports structural tree changes; Self::detect_rewrites infers content matches separately. Loose-object writes belong to LooseObjects, and reference updates belong to crate::refs.

Obtain this synchronous, blocking reader through crate::Repository::objects. Opening streams index bytes in the repository’s object format in filename order and verifies index v1/v2 structure (table sizes, sorted identities, fanout, offsets that tile the pack), pack v2/v3 headers/counts, and index/pack trailer agreement. Like Git, it does not hash the whole index at open. It reads only the pack header and trailer; body corruption is detected when used. Reads check entry framing, v2 CRCs, zlib streams and delta programs throughout reconstruction, and verify the requested object’s decoded identity, so a damaged index triggers verified fallback or an error rather than returning other content. Legacy v1 indexes have no entry CRCs. Self::verify_packs explicitly checks index checksums, whole-pack checksums and CRCs; neither opening nor whole-pack verification is a full fsck.

Pack bytes are never retained in full. Bounded index bytes and offset tables stay in memory so identity lookups avoid repeated file seeks. Each pair pins two handles, shared internally through Arc. Reads are positioned, so simultaneous reads share no cursor or lock; a typical entry’s header and compressed bytes come from one read. Cloning shares pack handles, offset tables and delta base caches, while copying the bounded store topology. Each pack keeps recently decoded entries, up to 96 MiB, as delta bases; a cached entry is still identity-checked before it is returned. Failed packed entries are remembered and skipped by subsequent content reads, shared by clones and preserved across refresh of unchanged pack generations (pinned size, modification time, native identity and trailer checksum). Metadata-only freshening of a still-pinned native artifact also preserves damage. PackLimits bounds aggregate opening work, index memory and handles; ReadLimits bounds each packed decode. Retention operations additionally share a single 256 KiB header window across packs on the calling thread, dropped when the operation ends. Windows artifact handles allow read/delete sharing and deny concurrent data writers. Concurrent reads and caller-owned results multiply memory use. Cancellation is available through crate::Repository::objects_controlled and Self::read_controlled.

Within each store, packs are searched in index filename order, followed by fresh loose reads. Stores are searched primary first, then alternates in discovery order. A corrupt packed entry falls through to the remaining copies, each fully verified. A corrupt loose copy normally fails immediately; after packed damage, it also falls through to the remaining stores. Known damaged entries remain excluded for this handle’s lifetime. Refresh retains small generation records without retaining old artifact handles or index tables. These records grow with distinct pack generations, including freshened metadata, opened by the handle and its clones. Packs remain readable after Git repacks/deletes the original files where the OS permits unlinking open files; refresh to discover new packs. Artifacts must remain immutable while readers use them: pinned handles do not defend against in-place writes (including truncation). Atomic path replacement leaves pinned artifacts intact. Opening and refresh validate each pinned pair, but do not capture an atomic directory or topology snapshot. Exclude writers when a point-in-time view is required. Self::refresh makes one bounded attempt and leaves this reader unchanged on failure. Reads never refresh implicitly. The object directory and its ancestors must be trusted, as with LooseObjects. This is not a snapshot of loose files or repository references.

Overlapping readers may share validated index buffers and tables through a process-local weak cache. Keys include native identity, size, mtime and Unix ctime or Windows ChangeTime. Shared validation owns independent artifact pins while readers or in-flight opens use that generation. Dropping its last reader releases those pins and buffers once any in-flight open finishes. Dead weak cache records retain neither buffers nor handles, so they do not keep deleted packs alive or Windows names delete-pending. Other snapshots or external processes can still pin the files. Opens after all readers drop validate again. Metadata keys do not replace immutable publication or caller-owned exclusion of in-place writers.

REF_DELTA bases must be indexed in the same pack. Thin packs and cross-pack/loose bases return ObjectReadError::MissingBase, even if the base exists elsewhere. Traversal is iterative, detects cycles, and enforces ReadLimits. Multi-pack indexes accelerate verified reads when usable; bitmap/reverse indexes are ignored; ordinary pack indexes remain required. Indexes are publication markers: unindexed packs are ignored, while an index without its pack is an opening error. A publisher must finish the pack before publishing its index. History queries use the repository handle’s immutable shallow boundaries; raw reads preserve commit parents. Reopen the repository or refresh its shallow snapshot, then create a new reader after Git deepening. Loose objects, packs and boundaries are not captured in one filesystem transaction; exclude concurrent depth changes while opening. Local alternate stores use the same format and aggregate pack limits; see crate::Repository::objects_with_alternates for topology and precedence. Complete partial-clone stores are readable; no missing-object fetch is attempted. Loose writes use LooseObjects; validated received-pack installation uses crate::fetch::ReceivedFetch::install.

The repository selects SHA-1 or SHA-256 for both artifacts. Their headers and filenames do not select the format. Every .idx filename is a publication marker, including noncanonical basenames; matching checksums and object identities validate contents independently of names.

Example

Read an object by full identity, then parse its exact bytes when structured fields are needed. Absence is Ok(None), not an error:

use girt::{InitKind, ObjectFormat, ObjectKind, PackLimits, ReadLimits, Repository, Tree};

let directory = tempfile::tempdir()?;
let repository = Repository::init(
    ObjectFormat::Sha1,
    directory.path().join("repo.git"),
    InitKind::Bare,
)?;
let tree = Tree::new(ObjectFormat::Sha1, vec![])?;
let id = repository.loose_objects().write_tree(&tree)?;

let objects = repository.objects_with(PackLimits::default())?;
let object = objects
    .read_with(id, ReadLimits::default())?
    .expect("tree was just written");
assert_eq!(object.kind(), ObjectKind::Tree);
assert!(
    Tree::parse(ObjectFormat::Sha1, object.data())?
        .entries()
        .is_empty()
);

let missing = ObjectFormat::Sha1.hash_object(ObjectKind::Blob, b"never written");
assert!(objects.read_with(missing, ReadLimits::default())?.is_none());

Implementations

impl Objects

pub fn without_bitmaps(self) -> Self

Returns this snapshot with bitmap shortcuts disabled, including after refresh.

Use this for independent graph verification or when derived metadata’s producer is not trusted. Queries still use the ordinary verified object reader.

pub fn reachable_difference( &self, include: &[ObjectId], exclude: &[ObjectId], ) -> Result<Reachability, Error>

Finds every object reachable from include except those reachable from exclude.

Roots may be commits, tags, trees or blobs. Tags are peeled, commit trees and parents are followed, tree gitlinks are skipped, and this snapshot’s shallow boundaries stop parent traversal. Sets are independent: exclusion never prunes the include walk. Missing roots or reachable objects are errors, so a server should pass only recognized have IDs.

Valid pack/MIDX bitmaps may replace covered commit walks. Missing, stale, unsupported, malformed or uncovered bitmap data falls back to walking. Bitmap checks establish inventory consistency, not graph truth; use Self::without_bitmaps for an independent walk.

Errors

Returns Error for missing, malformed or unreadable objects, mismatched edge types, or exhausted aggregate limits. No partial set is returned.

pub fn reachable_difference_with( &self, include: &[ObjectId], exclude: &[ObjectId], limits: QueryLimits, cancel: &AtomicBool, ) -> Result<Reachability, Error>

Finds a reachability difference under aggregate bounds and cooperative cancellation.

Limits cover both closures, metadata loading and repeated XOR expansion. Optional metadata that exceeds its bounds is skipped; graph-walk limits remain authoritative. A missing bitmap never makes an object unreachable. Filesystem reads and one bounded metadata parse or inventory verification cannot be interrupted.

Errors

Returns the errors of Self::reachable_difference or Error::Cancelled.

impl Objects

pub fn encode_pack_bitmap( &self, pack: ObjectId, options: WriteOptions, limits: WriteLimits, cancel: &AtomicBool, ) -> Result<Written, WriteError>

Encodes a pack bitmap and reverse index from verified contents without changing storage.

The selected primary pack must contain its entire graph closure, including unselected commits’ dependencies. Existing bitmap claims are never trusted. Explicit selection is deduplicated; the default selects graph tips first and samples remaining commits by ID. Selection is deterministic, not Git’s compression/commit-selection heuristic. Records use EWAH runs/literals without XOR dependencies and include a lookup table.

Keep maintenance exclusion through encoding and installation: retained handles alone cannot prevent another process from retiring the named pack. Source generations are rechecked before returning. The returned artifacts are private bytes, not installed files.

Errors

Returns WriteError for unavailable packs, incomplete or shallow graphs, corrupt sources, invalid selections, cancellation or exhausted limits. No partial output is returned.

pub fn encode_multi_pack_bitmap( &self, midx: WriteOptions, options: WriteOptions, limits: WriteLimits, cancel: &AtomicBool, ) -> Result<MultiPackWritten, WriteError>

Encodes a primary-store MIDX and associated bitmap/reverse index without changing files.

Uses the same graph/selection contract as Self::encode_pack_bitmap. The preferred pack comes first in pseudo-pack order and wins duplicate IDs; absent an explicit preference, the largest pack wins, with checksum order breaking ties. Output includes RIDX and BTMP chunks.

Errors

Returns WriteError for incomplete inventories, invalid inputs, cancellation or bounds.

impl Objects

pub fn blame( &self, commit: ObjectId, path: impl AsRef<[u8]>, ) -> Result<Vec<Hunk>, Error>

Attributes a regular file at a commit using default Limits. Wraps Self::blame_with; see the module contract.

Errors

Returns missing, malformed, unsupported, shallow-history or resource errors.

pub fn blame_with( &self, commit: ObjectId, path: impl AsRef<[u8]>, limits: Limits, cancel: &AtomicBool, ) -> Result<Vec<Hunk>, Error>

Attributes lines with explicit whole-walk bounds and cancellation.

An identical parent file takes precedence; otherwise parents are considered in stored order, passing unchanged lines to the first matching parent. Missing objects are errors, never history roots. Both SHA-1 and SHA-256 object stores are supported. No repository data is changed.

Errors

Returns Error without partial results. Increase the relevant limit or fetch missing history before retrying. Cancellation is checked between reads and during comparisons.

impl Objects

pub fn with_commit_graph(self, graph: CommitGraph) -> Result<Self, GraphError>

Attaches structurally checked auxiliary metadata for subsequent history queries.

This explicitly trusts the index’s object claims without decoding the named commits. Use CommitGraph::verify first when object verification is required. Missing index records use ordinary verified reads. Commit/parent query bounds and shallow boundaries still apply; per-object byte limits apply only to fallback reads. Typed object reads always use objects. Clones share the immutable index; storage refresh retains this index until replaced.

Errors

Rejects a different hash format or cyclic indexed ancestry. Parsing has already rejected parent positions that name no record.

Examples found in repository

examples/commit_graph_open_phases.rs (line 26)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut args = std::env::args().skip(1);
    let path = args.next().ok_or("repository path required")?;
    let rounds: usize = args.next().map_or(Ok(3), |r| r.parse())?;
    for _ in 0..rounds {
        let start = Instant::now();
        let repo = Repository::open(&path)?;
        let objects = repo
            .objects_with(PackLimits::trusted())?
            .without_commit_graph();
        let opened = start.elapsed();
        let start = Instant::now();
        let bytes = std::fs::read(repo.object_dir().join("info/commit-graph"))?;
        let read = start.elapsed();
        let start = Instant::now();
        let graph = CommitGraph::parse(&bytes, repo.object_format())?;
        let parsed = start.elapsed();
        let start = Instant::now();
        let objects = objects.with_commit_graph(graph)?;
        let attached = start.elapsed();
        let start = Instant::now();
        drop(objects);
        let dropped = start.elapsed();
        let start = Instant::now();
        let full = Repository::open(&path)?.objects_with(PackLimits::trusted())?;
        let total = start.elapsed();
        drop(full);
        eprintln!(
            "repo+packs={opened:?} read={read:?} parse={parsed:?} attach={attached:?} drop={dropped:?} default_open={total:?}"
        );
    }
    Ok(())
}

pub fn without_commit_graph(self) -> Self

Removes the auxiliary index so history queries read commit objects directly.

Useful when object claims must be checked during each query rather than trusted from an index. This does not alter repository configuration or other readers.

Examples found in repository

examples/commit_graph_open_phases.rs (line 17)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut args = std::env::args().skip(1);
    let path = args.next().ok_or("repository path required")?;
    let rounds: usize = args.next().map_or(Ok(3), |r| r.parse())?;
    for _ in 0..rounds {
        let start = Instant::now();
        let repo = Repository::open(&path)?;
        let objects = repo
            .objects_with(PackLimits::trusted())?
            .without_commit_graph();
        let opened = start.elapsed();
        let start = Instant::now();
        let bytes = std::fs::read(repo.object_dir().join("info/commit-graph"))?;
        let read = start.elapsed();
        let start = Instant::now();
        let graph = CommitGraph::parse(&bytes, repo.object_format())?;
        let parsed = start.elapsed();
        let start = Instant::now();
        let objects = objects.with_commit_graph(graph)?;
        let attached = start.elapsed();
        let start = Instant::now();
        drop(objects);
        let dropped = start.elapsed();
        let start = Instant::now();
        let full = Repository::open(&path)?.objects_with(PackLimits::trusted())?;
        let total = start.elapsed();
        drop(full);
        eprintln!(
            "repo+packs={opened:?} read={read:?} parse={parsed:?} attach={attached:?} drop={dropped:?} default_open={total:?}"
        );
    }
    Ok(())
}

examples/commit_graph_profile.rs (line 24)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut args = std::env::args().skip(1);
    let path = args.next().ok_or("repository path required")?;
    let tip: ObjectId = args.next().ok_or("tip ID required")?.parse()?;
    let base: ObjectId = args.next().ok_or("base ID required")?.parse()?;
    let trust = args.next().ok_or("objects, indexed or verified required")?;
    let query = args.next().ok_or("walk, range or ancestor required")?;
    let start = Instant::now();
    let repo = Repository::open(path)?;
    let mut objects = repo.objects_with(PackLimits::trusted())?;
    eprintln!("open={:?}", start.elapsed());
    match trust.as_str() {
        "objects" => objects = objects.without_commit_graph(),
        "indexed" => {}
        "verified" => {
            let graph = repo.commit_graph()?.ok_or("commit-graph required")?;
            let start = Instant::now();
            graph.verify(&objects)?;
            eprintln!("object_verification={:?}", start.elapsed());
        }
        _ => return Err("unknown trust choice".into()),
    }
    let start = Instant::now();
    let limits = HistoryLimits::trusted();
    match query.as_str() {
        "walk" => println!("{}", objects.walk_with(&[tip], limits)?.len()),
        "range" => println!(
            "{}",
            objects.walk_range_with(&[tip], &[base], limits)?.len()
        ),
        "ancestor" => println!("{}", objects.is_ancestor_with(base, tip, limits)?),
        _ => return Err("unknown query".into()),
    }
    eprintln!("query={:?}", start.elapsed());
    Ok(())
}

impl Objects

pub fn encode_multi_pack_index( &self, options: WriteOptions, ) -> Result<Vec<u8>, WriteError>

Encodes a monolithic v1 MIDX for the primary store with default bounds.

See Self::encode_multi_pack_index_with for source validation and publication contracts.

Errors

Returns WriteError for invalid sources, selection or exhausted bounds.

use girt::Repository;
use girt::multi_pack_index::{MultiPackIndex, WriteOptions};
let repository = Repository::open("repo.git")?;
let objects = repository.objects()?;
let mut options = WriteOptions::default();
options.preferred_pack = objects
    .stores()
    .next()
    .and_then(|store| store.packs().next())
    .map(|pack| pack.checksum());
let bytes = objects.encode_multi_pack_index(options)?;
let index = MultiPackIndex::parse(&bytes, repository.object_format())?;
println!("{} unique packed objects", index.len());
// Keep these bytes private until installation can exclude repacking and pruning.

pub fn encode_multi_pack_index_with( &self, options: WriteOptions, limits: WriteLimits, cancel: &AtomicBool, ) -> Result<Vec<u8>, WriteError>

Encodes verified primary-store indexes into caller-owned bytes without filesystem mutation.

Alternate packs are excluded. Every source index’s checksum and structure are checked before its identities are copied. Duplicate objects use options; sorted IDs and names make output deterministic for the same inputs. Pack payloads are not scanned. The caller must exclude repacking or pruning while constructing and installing an artifact; a retained snapshot can otherwise name packs already removed from the directory. Source generation changes refuse encoding. Use the repository publication API for coordinated installation.

Errors

Returns WriteError for changed or damaged indexes, unknown preferred packs, unsupported filenames, cancellation or exhausted input/output bounds. No partial bytes are returned.

impl Objects

pub fn walk_path_first_parent( &self, root: ObjectId, path: &[u8], ) -> Result<Vec<ObjectId>, PathHistoryError>

Finds commits changing a literal path along the first-parent chain, newest first.

Compares entry identity and mode against the first parent, or an empty snapshot at a root or declared shallow boundary. Includes additions and deletions. Directories compare their subtree identities; pathspecs and rename following are not performed. An explicitly attached graph can skip tree comparisons using Bloom negatives. Missing or uncertain filters always require ordinary comparison. Uses default history and per-read bounds.

Errors

Reports invalid paths, missing/corrupt commits or trees on the selected path, cycles and exhausted bounds. Bloom-skipped trees and side-parent histories are not read or verified.

pub fn walk_path_first_parent_with( &self, root: ObjectId, path: &[u8], limits: HistoryLimits, ) -> Result<Vec<ObjectId>, PathHistoryError>

Finds first-parent path changes with explicit history and per-object read limits.

Errors

Returns the same errors as Self::walk_path_first_parent. Commit bounds count visited first-parent commits; parent bounds count followed first-parent edges. Each tree read uses limits.read; memory includes returned IDs and the visited set, plus one decoded tree.

impl Objects

pub fn walk_range( &self, include: &[ObjectId], exclude: &[ObjectId], ) -> Result<Vec<ObjectId>, HistoryError>

Collects commits reachable from include but not from exclude, using default bounds.

Every result appears once; result order is unspecified. With an attached index covering every root and a checked strict generation order, traversal stops when no interesting commit remains queued. Otherwise it collects both closures. Shallow boundaries stop edges.

Errors

Returns history read, kind, parse, cycle or resource errors for explored commits. Indexed metadata uses the explicit trust contract of Self::with_commit_graph. Ancestors beyond a generation stopping boundary are not read or verified.

pub fn walk_range_with( &self, include: &[ObjectId], exclude: &[ObjectId], limits: HistoryLimits, ) -> Result<Vec<ObjectId>, HistoryError>

Collects a reachability difference under explicit commit, edge and fallback-read bounds.

Errors

Returns the same errors as Self::walk_range. Bounds count both sides, including excluded commits actually explored. Empty includes return immediately without storage access.

Examples found in repository

examples/commit_graph_profile.rs (line 40)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut args = std::env::args().skip(1);
    let path = args.next().ok_or("repository path required")?;
    let tip: ObjectId = args.next().ok_or("tip ID required")?.parse()?;
    let base: ObjectId = args.next().ok_or("base ID required")?.parse()?;
    let trust = args.next().ok_or("objects, indexed or verified required")?;
    let query = args.next().ok_or("walk, range or ancestor required")?;
    let start = Instant::now();
    let repo = Repository::open(path)?;
    let mut objects = repo.objects_with(PackLimits::trusted())?;
    eprintln!("open={:?}", start.elapsed());
    match trust.as_str() {
        "objects" => objects = objects.without_commit_graph(),
        "indexed" => {}
        "verified" => {
            let graph = repo.commit_graph()?.ok_or("commit-graph required")?;
            let start = Instant::now();
            graph.verify(&objects)?;
            eprintln!("object_verification={:?}", start.elapsed());
        }
        _ => return Err("unknown trust choice".into()),
    }
    let start = Instant::now();
    let limits = HistoryLimits::trusted();
    match query.as_str() {
        "walk" => println!("{}", objects.walk_with(&[tip], limits)?.len()),
        "range" => println!(
            "{}",
            objects.walk_range_with(&[tip], &[base], limits)?.len()
        ),
        "ancestor" => println!("{}", objects.is_ancestor_with(base, tip, limits)?),
        _ => return Err("unknown query".into()),
    }
    eprintln!("query={:?}", start.elapsed());
    Ok(())
}

examples/range_timing.rs (line 37)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut args = std::env::args().skip(1);
    let path = args.next().ok_or("expected repository path")?;
    let rounds: usize = args.next().ok_or("expected number of rounds")?.parse()?;
    let start = Instant::now();
    let repo = Repository::open(path)?;
    let objects = repo.objects_with(PackLimits::trusted())?;
    println!("open {:.1} ms", ms(start.elapsed()));
    for pair in args {
        let (left, right) = pair.split_once("...").ok_or("expected LEFT...RIGHT")?;
        let (left, right): (ObjectId, ObjectId) = (left.parse()?, right.parse()?);
        let mut counts = None;
        let mut best_counts = Duration::MAX;
        let mut walked = 0;
        let mut best_walk = Duration::MAX;
        for _ in 0..rounds {
            let start = Instant::now();
            counts = Some(black_box(objects.ahead_behind_with(
                left,
                right,
                HistoryLimits::trusted(),
            )?));
            best_counts = best_counts.min(start.elapsed());
            let start = Instant::now();
            walked =
                black_box(objects.walk_range_with(&[right], &[left], HistoryLimits::trusted())?)
                    .len();
            best_walk = best_walk.min(start.elapsed());
        }
        let counts = counts.ok_or("expected at least one round")?;
        println!(
            "{pair}: ahead {} behind {} in {:.2} ms; range {walked} in {:.2} ms",
            counts.ahead,
            counts.behind,
            ms(best_counts),
            ms(best_walk),
        );
    }
    Ok(())
}

impl Objects

pub fn ahead_behind( &self, left: ObjectId, right: ObjectId, ) -> Result<AheadBehind, HistoryError>

Counts the commits only left reaches and the commits only right reaches.

This is git rev-list --left-right --count left...right: with left a branch and right its upstream, AheadBehind::ahead is how many commits the branch has that the upstream lacks. Equal tips give zero on both sides; disconnected histories count every commit.

With a commit-graph covering both tips, the walk visits commits in descending generation order and stops once every queued commit is reachable from both tips, so shared history below the merge base is not read. Without one, both complete ancestries are read. Both give exact counts; no timestamp heuristics are used.

let base = commit(vec![], b"base\n")?;
let local = commit(vec![base], b"local\n")?;
let upstream = commit(vec![base], b"upstream 1\n")?;
let upstream = commit(vec![upstream], b"upstream 2\n")?;

let counts = repo.objects()?.ahead_behind(local, upstream)?;
assert_eq!((counts.ahead, counts.behind), (1, 2));

Errors

Returns the errors of Self::walk_range.

pub fn ahead_behind_with( &self, left: ObjectId, right: ObjectId, limits: HistoryLimits, ) -> Result<AheadBehind, HistoryError>

Counts both sides of a symmetric range under explicit bounds.

Errors

Returns the errors of Self::walk_range_with; bounds count commits explored on both sides.

Examples found in repository

examples/range_timing.rs (lines 29-33)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut args = std::env::args().skip(1);
    let path = args.next().ok_or("expected repository path")?;
    let rounds: usize = args.next().ok_or("expected number of rounds")?.parse()?;
    let start = Instant::now();
    let repo = Repository::open(path)?;
    let objects = repo.objects_with(PackLimits::trusted())?;
    println!("open {:.1} ms", ms(start.elapsed()));
    for pair in args {
        let (left, right) = pair.split_once("...").ok_or("expected LEFT...RIGHT")?;
        let (left, right): (ObjectId, ObjectId) = (left.parse()?, right.parse()?);
        let mut counts = None;
        let mut best_counts = Duration::MAX;
        let mut walked = 0;
        let mut best_walk = Duration::MAX;
        for _ in 0..rounds {
            let start = Instant::now();
            counts = Some(black_box(objects.ahead_behind_with(
                left,
                right,
                HistoryLimits::trusted(),
            )?));
            best_counts = best_counts.min(start.elapsed());
            let start = Instant::now();
            walked =
                black_box(objects.walk_range_with(&[right], &[left], HistoryLimits::trusted())?)
                    .len();
            best_walk = best_walk.min(start.elapsed());
        }
        let counts = counts.ok_or("expected at least one round")?;
        println!(
            "{pair}: ahead {} behind {} in {:.2} ms; range {walked} in {:.2} ms",
            counts.ahead,
            counts.behind,
            ms(best_counts),
            ms(best_walk),
        );
    }
    Ok(())
}

impl Objects

pub fn simplify_commit( &self, commit: &Commit, parents: &[ObjectId], paths: &Pathspec, limits: TreeCompareLimits, cancel: &AtomicBool, ) -> Result<Simplification, SimplifyError>

Decides whether commit appears in git log -- <paths> and which parents the walk follows.

A commit is TREESAME to a parent when no selected path differs between their trees. Following Git’s default simplification:

• a root commit is shown when its tree holds a selected path;
• a commit with one parent is shown unless it is TREESAME to it, and the parent is followed;
• a merge TREESAME to some parent is hidden, and only the first such parent is followed, so side branches that did not change the paths are not walked;
• any other merge is shown and every parent is followed.

Pass parents as the IDs the walk should consider, normally Commit::parents; pass an empty slice at a shallow boundary, where the commit is compared with an empty tree like a root. Parent commits are read with TreeCompareLimits::read to find their trees. --full-history, --simplify-merges, parent rewriting and --follow are not provided.

use std::sync::atomic::AtomicBool;

use girt::pathspec::{Context, Pathspec};
use girt::tree::TreeEditor;
use girt::{Commit, CommitFields, InitKind, ObjectFormat, Repository, Signature};

let directory = tempfile::tempdir()?;
let repo = Repository::init(
    ObjectFormat::Sha1,
    directory.path().join("r"),
    InitKind::Bare,
)?;
let loose = repo.loose_objects();
let person = Signature {
    name: b"A. Writer".to_vec(),
    email: b"writer@example.com".to_vec(),
    seconds: 1_700_000_000,
    offset_minutes: 0,
};
let mut editor = TreeEditor::new(&loose);
let mut commit = |path: &[u8], parents: Vec<_>| -> Result<_, Box<dyn std::error::Error>> {
    editor.set(path, loose.write_blob(path)?)?;
    let fields = CommitFields {
        tree: editor.write()?,
        parents,
        author: person.clone(),
        committer: person.clone(),
        extra_headers: vec![],
        message: b"change\n".to_vec(),
    };
    Ok(loose.write_commit(&Commit::new(fields)?)?)
};
let first = commit(b"src/lib.rs", vec![])?;
let second = commit(b"docs/guide.md", vec![first])?;

let objects = repo.objects()?;
let paths = Pathspec::parse(["src"], &Context::new())?;
let cancel = AtomicBool::new(false);
let step = |id| -> Result<_, Box<dyn std::error::Error>> {
    let commit = objects.read_commit(id)?;
    let parents = commit.parents().to_vec();
    Ok(objects.simplify_commit(&commit, &parents, &paths, Default::default(), &cancel)?)
};
// `second` only touched docs, so `git log -- src` skips it and continues to `first`.
assert!(!step(second)?.shown);
assert_eq!(step(second)?.follow, [first]);
assert!(step(first)?.shown);

Errors

Returns SimplifyError::Parent when a parent cannot be read and SimplifyError::Trees when a tree comparison fails, including TreeCompareError::Unsupported for attr: magic.

impl Objects

pub fn walk_with( &self, roots: &[ObjectId], limits: HistoryLimits, ) -> Result<Vec<ObjectId>, HistoryError>

Collects all commits reachable from explicit roots, including the roots themselves.

Order is breadth-first: roots in supplied order, then parents in stored order. First discovery wins; duplicate roots and parents never duplicate output. This is not topological order: an ancestor supplied as a root can precede its descendant. Timestamps are ignored. Declared shallow roots are read and parsed but their parent edges are not followed, even when parent objects exist. Raw commit reads retain every parent. An empty root slice returns an empty vector without reading storage.

use girt::{
    Commit, CommitFields, HistoryLimits, InitKind, ObjectFormat, PackLimits, Repository,
    Signature, Tree,
};

let directory = tempfile::tempdir()?;
let repository = Repository::init(
    ObjectFormat::Sha1,
    directory.path().join("repo.git"),
    InitKind::Bare,
)?;

let loose = repository.loose_objects();
let tree = loose.write_tree(&Tree::new(ObjectFormat::Sha1, vec![])?)?;
let person = Signature {
    name: b"A. Writer".to_vec(),
    email: b"writer@example.com".to_vec(),
    seconds: 1_700_000_000,
    offset_minutes: 0,
};
let commit = |parents, message: &[u8]| {
    loose.write_commit(&Commit::new(CommitFields {
        tree,
        parents,
        author: person.clone(),
        committer: person.clone(),
        extra_headers: vec![],
        message: message.to_vec(),
    })?)
};

let first = commit(vec![], b"first\n")?;
let second = commit(vec![first], b"second\n")?;

let objects = repository.objects_with(PackLimits::default())?;
assert_eq!(
    objects.walk_with(&[second], HistoryLimits::default())?,
    [second, first]
);

// Supplied root order wins over ancestry: the walk is not topological.
let limits = HistoryLimits::default();
assert_eq!(
    objects.walk_with(&[first, second], limits)?,
    [first, second]
);
assert!(objects.is_ancestor_with(first, second, HistoryLimits::default())?);
assert!(!objects.is_ancestor_with(second, first, HistoryLimits::default())?);

Errors

Returns HistoryError on any reachable missing, non-commit, malformed or corrupt object, cycle, or exhausted bound. No partial result is returned and no files are changed. Commit syntax uses Commit::parse without additional field validation; trees are not read.

Examples found in repository

examples/commit_graph_profile.rs (line 37)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut args = std::env::args().skip(1);
    let path = args.next().ok_or("repository path required")?;
    let tip: ObjectId = args.next().ok_or("tip ID required")?.parse()?;
    let base: ObjectId = args.next().ok_or("base ID required")?.parse()?;
    let trust = args.next().ok_or("objects, indexed or verified required")?;
    let query = args.next().ok_or("walk, range or ancestor required")?;
    let start = Instant::now();
    let repo = Repository::open(path)?;
    let mut objects = repo.objects_with(PackLimits::trusted())?;
    eprintln!("open={:?}", start.elapsed());
    match trust.as_str() {
        "objects" => objects = objects.without_commit_graph(),
        "indexed" => {}
        "verified" => {
            let graph = repo.commit_graph()?.ok_or("commit-graph required")?;
            let start = Instant::now();
            graph.verify(&objects)?;
            eprintln!("object_verification={:?}", start.elapsed());
        }
        _ => return Err("unknown trust choice".into()),
    }
    let start = Instant::now();
    let limits = HistoryLimits::trusted();
    match query.as_str() {
        "walk" => println!("{}", objects.walk_with(&[tip], limits)?.len()),
        "range" => println!(
            "{}",
            objects.walk_range_with(&[tip], &[base], limits)?.len()
        ),
        "ancestor" => println!("{}", objects.is_ancestor_with(base, tip, limits)?),
        _ => return Err("unknown query".into()),
    }
    eprintln!("query={:?}", start.elapsed());
    Ok(())
}

pub fn is_ancestor_with( &self, ancestor: ObjectId, descendant: ObjectId, limits: HistoryLimits, ) -> Result<bool, HistoryError>

Tests whether ancestor is reachable from descendant, including equality.

Errors

Without an attached commit-graph, validates both complete ancestries before answering. With trusted indexed metadata and checked generation order, stops at the target generation or an early match. Returns the same failures as Self::walk for explored data.

assert!(objects.is_ancestor_with(base, left, HistoryLimits::default())?);
assert!(objects.is_ancestor_with(left, left, HistoryLimits::default())?);
assert!(!objects.is_ancestor_with(left, right, HistoryLimits::default())?);

Examples found in repository

examples/commit_graph_profile.rs (line 42)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut args = std::env::args().skip(1);
    let path = args.next().ok_or("repository path required")?;
    let tip: ObjectId = args.next().ok_or("tip ID required")?.parse()?;
    let base: ObjectId = args.next().ok_or("base ID required")?.parse()?;
    let trust = args.next().ok_or("objects, indexed or verified required")?;
    let query = args.next().ok_or("walk, range or ancestor required")?;
    let start = Instant::now();
    let repo = Repository::open(path)?;
    let mut objects = repo.objects_with(PackLimits::trusted())?;
    eprintln!("open={:?}", start.elapsed());
    match trust.as_str() {
        "objects" => objects = objects.without_commit_graph(),
        "indexed" => {}
        "verified" => {
            let graph = repo.commit_graph()?.ok_or("commit-graph required")?;
            let start = Instant::now();
            graph.verify(&objects)?;
            eprintln!("object_verification={:?}", start.elapsed());
        }
        _ => return Err("unknown trust choice".into()),
    }
    let start = Instant::now();
    let limits = HistoryLimits::trusted();
    match query.as_str() {
        "walk" => println!("{}", objects.walk_with(&[tip], limits)?.len()),
        "range" => println!(
            "{}",
            objects.walk_range_with(&[tip], &[base], limits)?.len()
        ),
        "ancestor" => println!("{}", objects.is_ancestor_with(base, tip, limits)?),
        _ => return Err("unknown query".into()),
    }
    eprintln!("query={:?}", start.elapsed());
    Ok(())
}

pub fn merge_bases_with( &self, left: ObjectId, right: ObjectId, limits: HistoryLimits, ) -> Result<Vec<ObjectId>, HistoryError>

Returns all best common ancestors of two commits, sorted by raw object ID.

A best common ancestor has no distinct common descendant. Criss-cross histories can return several bases; disconnected histories return none and identical endpoints return themselves. Runs in O(V + E) graph work plus O(B log B) sorting for B bases, without timestamp assumptions.

Errors

Validates both complete ancestries; returns the same failures as Self::walk.

assert_eq!(objects.merge_bases_with(left, right, HistoryLimits::default())?, [base]);
assert_eq!(objects.merge_bases_with(left, left, HistoryLimits::default())?, [left]);

pub fn walk(&self, roots: &[ObjectId]) -> Result<Vec<ObjectId>, HistoryError>

Collects the commits reachable from roots with HistoryLimits::default.

Equivalent to self.walk_with(roots, HistoryLimits::default()); see Self::walk_with.

Errors

Returns the errors of Self::walk_with.

Examples found in repository

examples/scheduling/fixture.rs (line 94)

    pub fn operation(&self, gate: Option<Gate>) {
        let repo = Repository::open(self.root.path()).unwrap();
        let objects = repo.objects().unwrap();

        if let Some(gate) = gate {
            gate.started.send(()).unwrap();
            gate.release.recv().unwrap();
        }

        let blob = objects.read(self.blob).unwrap().unwrap();
        assert_eq!(blob.data().len(), 2 * 1024 * 1024);
        assert_eq!(objects.walk(&[self.tip]).unwrap().len(), 512);
    }

pub fn is_ancestor( &self, ancestor: ObjectId, descendant: ObjectId, ) -> Result<bool, HistoryError>

Tests ancestry with HistoryLimits::default.

Equivalent to self.is_ancestor_with(ancestor, descendant, HistoryLimits::default()); see Self::is_ancestor_with.

Errors

Returns the errors of Self::is_ancestor_with.

Examples found in repository

examples/history.rs (line 30)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let args = Args::parse();
    let root = args.commit;
    let git = Repo::discover(args.path)?;

    for entry in git.log(root)? {
        let (id, _) = entry?;
        println!("{id}");
    }

    if let Some(other) = args.other_commit {
        let objects = git.repository().objects()?;
        println!("ancestor: {}", objects.is_ancestor(root, other)?);
        println!("merge bases: {:?}", objects.merge_bases(root, other)?);
    }

    Ok(())
}

pub fn merge_bases( &self, left: ObjectId, right: ObjectId, ) -> Result<Vec<ObjectId>, HistoryError>

Finds every best common ancestor with HistoryLimits::default.

Equivalent to self.merge_bases_with(left, right, HistoryLimits::default()); see Self::merge_bases_with.

Errors

Returns the errors of Self::merge_bases_with.

Examples found in repository

examples/history.rs (line 31)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let args = Args::parse();
    let root = args.commit;
    let git = Repo::discover(args.path)?;

    for entry in git.log(root)? {
        let (id, _) = entry?;
        println!("{id}");
    }

    if let Some(other) = args.other_commit {
        let objects = git.repository().objects()?;
        println!("ancestor: {}", objects.is_ancestor(root, other)?);
        println!("merge bases: {:?}", objects.merge_bases(root, other)?);
    }

    Ok(())
}

impl Objects

pub fn merge_commits( &self, ours: ObjectId, theirs: ObjectId, ) -> Result<CommitMerge, CommitError>

Merges commit tips using every best common ancestor and default bounds.

See Self::merge_commits_with for recursive-base and publication contracts.

Errors

Returns CommitError on unrelated history, unreadable inputs, incomplete tree merging, unresolved virtual bases, exhausted bounds or cancellation.

use girt::{Commit, InitKind, ObjectFormat, Repository, Signature, Tree};
let temporary = tempfile::tempdir()?;
let repo = Repository::init(
    ObjectFormat::Sha1,
    temporary.path().join("repo"),
    InitKind::Bare,
)?;
let loose = repo.loose_objects();
let tree = loose.write_tree(&Tree::new(ObjectFormat::Sha1, vec![])?)?;
let person = Signature {
    name: b"Merge Author".to_vec(),
    email: b"merge@example.com".to_vec(),
    seconds: 1_700_000_000,
    offset_minutes: 0,
};
let base = loose.write_commit(&Commit::builder(tree, person.clone(), b"base\n").build()?)?;
let ours = loose.write_commit(
    &Commit::builder(tree, person.clone(), b"ours\n")
        .parent(base)
        .build()?,
)?;
let theirs = loose.write_commit(
    &Commit::builder(tree, person.clone(), b"theirs\n")
        .parent(base)
        .build()?,
)?;
let merged = repo.objects()?.merge_commits(ours, theirs)?;
assert!(merged.result.is_clean());
for (_, bytes) in &merged.result.blobs {
    loose.write_blob(bytes)?;
}
for tree in &merged.result.trees {
    loose.write_tree(tree)?;
}
let commit = Commit::builder(merged.result.tree.id(), person, b"merge\n")
    .parents(merged.parents)
    .build()?;
let id = loose.write_commit(&commit)?;
assert_eq!(repo.objects()?.read_commit(id)?.parents(), &[ours, theirs]);
// The object is stored; no reference has moved.

pub fn merge_commits_with( &self, ours: ObjectId, theirs: ObjectId, options: CommitOptions, cancel: &AtomicBool, ) -> Result<CommitMerge, CommitError>

Computes a rename-aware commit merge without a working tree or object-store mutation.

Finds all best common ancestors using the existing history traversal. Multiple bases are folded in object-ID order. Each fold recursively synthesizes the best common ancestors of the accumulated original base tips and the next tip. Generated trees and blobs remain in memory and are available to later folds, including rename scoring. A conflicted virtual base returns CommitError::ConflictedBase rather than choosing a provisional ancestor.

Unrelated original tips require explicit opt-in. An empty base is always permitted inside recursive synthesis. Bounds apply independently to ancestry queries and tree comparisons; depth, base-set and virtual-merge limits bound composition. Individual history/storage reads and sorting are not interruptible; cancellation is checked between operations. No commit, index, working file or reference is written. Final conflicts remain a result.

Errors

Returns CommitError with original causes and unresolved virtual-base data. No partial result is installed, so retrying computation requires no repository rollback.

pub fn merge_commits_with_driver( &self, ours: ObjectId, theirs: ObjectId, options: CommitOptions, cancel: &AtomicBool, driver: &mut dyn TreeDriver, ) -> Result<CommitMerge, CommitError>

Merges commit tips using one path-driver instance for recursive bases and final content.

Uses Self::merge_commits_with’s bounds, history policy and in-memory result contract. Callback side effects and attribute snapshot choice belong to the caller; no implicit command runs. See super::TreeDriver for attribute and custom-driver composition.

Errors

Returns CommitError, retaining any driver failure’s path and original source.

impl Objects

pub fn merge_trees_with_driver( &self, base: ObjectId, ours: ObjectId, theirs: ObjectId, options: TreeMergeOptions, cancel: &AtomicBool, driver: &mut dyn TreeDriver, ) -> Result<TreeMerge, RenameError>

Merges renamed trees with explicit per-path content-driver dispatch.

Uses Self::merge_trees_with’s path/inference policy. The driver receives destination paths after alignment and original base/side payloads; callback errors retain path/source. No implicit attribute lookup or shell command runs. See TreeDriver for composition.

Errors

Returns RenameError for inference/tree failures, including path-driver errors.

impl Objects

pub fn merge_trees( &self, base: ObjectId, ours: ObjectId, theirs: ObjectId, ) -> Result<TreeMerge, RenameError>

Merges three trees with rename inference and default bounds, without writing objects.

See Self::merge_trees_with for conflict and unsupported-layout contracts.

Errors

Returns RenameError on incomplete inference, unsupported alignment or tree failures.

use girt::{InitKind, ObjectFormat, Repository, Tree};
let temporary = tempfile::tempdir()?;
let repo = Repository::init(
    ObjectFormat::Sha1,
    temporary.path().join("repo"),
    InitKind::Bare,
)?;
let empty = repo
    .loose_objects()
    .write_tree(&Tree::new(ObjectFormat::Sha1, vec![])?)?;
let result = repo.objects()?.merge_trees(empty, empty, empty)?;
assert!(result.is_clean());
assert_eq!(result.tree.id(), empty);

pub fn merge_trees_with( &self, base: ObjectId, ours: ObjectId, theirs: ObjectId, options: TreeMergeOptions, cancel: &AtomicBool, ) -> Result<TreeMerge, RenameError>

Aligns renamed paths, then merges content and modes entirely in memory.

Base-to-side inference uses the existing rewrite detector. One-sided renames carry an opposite-side modification to the destination. Distinct rename destinations and rename/delete remain structured conflicts with original entries. Removed directories with one inferred destination relocate opposite-side additions and report directory-rename conflicts, matching Git’s default conservative directory-addition policy.

Destination collisions, ambiguous directory moves, skipped inexact inference and stored empty subdirectories are explicit errors rather than deletion/addition approximations. Input normalization trees and clean merged blobs stay in TreeMerge; install generated objects before publishing its root. No attributes, configuration or submodules are opened. Each traversal/comparison has its own bounds. Cancellation discards the entire result.

Errors

Returns RenameError for inference, layout, object-read, content or traversal failures.

impl Objects

pub fn merge_tree_entries( &self, base: ObjectId, ours: ObjectId, theirs: ObjectId, ) -> Result<TreeMerge, TreeError>

Merges three tree snapshots by path with default bounds and no cancellation.

This primitive does not infer renames. See Self::merge_tree_entries_with for the computation/publication boundary and TreeMerge for generated object ownership.

Errors

Returns input object, content comparison, tree validation or traversal errors.

use girt::{InitKind, ObjectFormat, Repository, Tree};
let directory = tempfile::tempdir()?;
let repo = Repository::init(
    ObjectFormat::Sha1,
    directory.path().join("repo"),
    InitKind::Bare,
)?;
let empty = Tree::new(repo.object_format(), vec![])?;
let id = repo.loose_objects().write_tree(&empty)?;
let result = repo.objects()?.merge_tree_entries(id, id, id)?;
assert!(result.is_clean());
assert_eq!(result.tree.id(), id);

pub fn merge_tree_entries_with( &self, base: ObjectId, ours: ObjectId, theirs: ObjectId, options: TreeOptions, cancel: &AtomicBool, ) -> Result<TreeMerge, TreeError>

Merges entries at matching paths without rename inference or working-tree access.

Exact entry equality and unchanged-side selection precede content comparison. Directories merge recursively; regular-file modes and payloads merge independently. Different symlink targets, entry types and gitlinks remain structured conflicts. Add/add regular files use an empty content base. Modify/delete preserves the surviving entry provisionally. No submodule repository is opened. Paths and file payloads remain bytes.

Generated blobs/trees stay in memory; no object store, index, working file or reference is mutated. Read errors discard the entire result. Callers own input-store retention during computation and installation. Rename-aware callers must reconcile renamed paths separately.

Errors

Returns TreeError on unreadable/wrong-kind inputs, content limits, cancellation, traversal bounds or invalid generated trees. Reused input subtrees are not validated.

impl Objects

pub fn header( &self, id: ObjectId, limits: ReadLimits, ) -> Result<Option<ObjectHeader>, ObjectReadError>

Reads id’s kind and size from its stored header without decoding the payload.

Uses the same store and pack precedence as Self::read. Packed deltas follow their chain headers to the base kind; the size comes from the delta’s own header. This is the lookup behind git cat-file --batch-check. The empty tree is reported even when not stored, as Self::read does.

Errors

Returns corrupt or unsupported headers, I/O errors, missing delta bases, or ObjectReadError::Limit when the size exceeds ReadLimits::max_object_bytes or the chain exceeds ReadLimits::max_delta_depth.

use girt::{InitKind, ObjectFormat, ObjectKind, PackLimits, ReadLimits, Repository};

let directory = tempfile::tempdir()?;
let repo = Repository::init(
    ObjectFormat::Sha1,
    directory.path().join("r.git"),
    InitKind::Bare,
)?;

let id = repo.loose_objects().write_blob(b"seven\n")?;
let objects = repo.objects_with(PackLimits::default())?;
let header = objects
    .header(id, ReadLimits::default())?
    .ok_or("missing")?;
assert_eq!((header.kind(), header.size()), (ObjectKind::Blob, 6));

pub fn headers( &self, ids: impl IntoIterator<Item = ObjectId>, limits: ReadLimits, ) -> Result<Vec<(ObjectId, Option<ObjectHeader>)>, ObjectReadError>

Reads the headers of many objects, visiting packed entries in pack order.

Equivalent to calling Self::header for each identity, but shared delta-chain headers are read once per call and pack reads proceed in file order, which matters for listing a whole repository. Results pair each identity with its header, or None when absent; their order is unspecified. Use Self::headers_controlled to cancel.

Errors

Returns the errors of Self::header.

pub fn headers_controlled( &self, ids: impl IntoIterator<Item = ObjectId>, limits: ReadLimits, cancelled: &AtomicBool, ) -> Result<Vec<(ObjectId, Option<ObjectHeader>)>, ObjectReadError>

Reads the headers of many objects as Self::headers does, checking cancelled between objects.

Errors

Returns the errors of Self::header or ObjectReadError::Cancelled.

impl Objects

pub fn stores(&self) -> impl ExactSizeIterator<Item = ObjectStore<'_>>

Returns this reader’s object stores in search order: the primary store, then alternates.

use girt::{InitKind, ObjectFormat, PackLimits, Repository};

let directory = tempfile::tempdir()?;
let repo = Repository::init(
    ObjectFormat::Sha1,
    directory.path().join("r.git"),
    InitKind::Bare,
)?;

let objects = repo.objects_with(PackLimits::default())?;
let stores: Vec<_> = objects.stores().collect();
assert_eq!(stores.len(), 1);
assert!(!stores[0].is_alternate());

pub fn packs(&self) -> impl Iterator<Item = IndexedPack<'_>>

Returns every pinned pack in search order, across the primary store and alternates.

Equivalent to flattening ObjectStore::packs over Self::stores.

Examples found in repository

examples/midx_lookup_timing.rs (line 27)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut args = std::env::args().skip(1);
    let path = args.next().ok_or("expected repository path")?;
    let list = args.next().ok_or("expected object-ID list path")?;
    let rounds: usize = args.next().ok_or("expected number of rounds")?.parse()?;
    let mode = args.next().unwrap_or_else(|| "read".to_owned());
    let ids = std::fs::read_to_string(list)?
        .lines()
        .map(str::parse)
        .collect::<Result<Vec<ObjectId>, _>>()?;
    let repo = Repository::open(path)?;
    let start = Instant::now();
    let objects = repo.objects()?;
    let opening = start.elapsed();
    let packs: Vec<_> = objects.packs().collect();
    let bytes = if mode == "midx" {
        std::fs::read(repo.object_dir().join("pack/multi-pack-index"))?
    } else {
        Vec::new()
    };
    let midx = if mode == "midx" {
        Some(girt::multi_pack_index::MultiPackIndex::parse(
            &bytes,
            repo.object_format(),
        )?)
    } else {
        None
    };
    let start = Instant::now();
    let mut found = 0_usize;
    for _ in 0..rounds {
        for id in &ids {
            let present = match mode.as_str() {
                "read" => {
                    black_box(objects.read(*id)?.ok_or("object absent")?);
                    true
                }
                "contains" => objects.contains(*id)?,
                "index-scan" => scan(&packs, *id)?,
                "midx" => midx.as_ref().ok_or("index absent")?.find(*id).is_some(),
                _ => return Err("expected read, contains, index-scan or midx".into()),
            };
            found += usize::from(black_box(present));
        }
    }
    println!(
        "objects={} rounds={rounds} mode={mode} found={found} open_ns={} read_ns={}",
        ids.len(),
        opening.as_nanos(),
        start.elapsed().as_nanos(),
    );
    Ok(())
}

pub fn object_ids( &self, limits: ListLimits, ) -> Result<Vec<ObjectId>, ObjectReadError>

Collects every object identity visible to this reader, sorted and without duplicates.

Includes all pinned packs and the current loose objects of every store, alternates included, as git cat-file --batch-all-objects lists them. The implicit empty tree is not included unless it is stored. See Self::object_ids_controlled for limits.

Errors

Returns the errors of Self::object_ids_controlled.

use girt::{InitKind, ListLimits, ObjectFormat, PackLimits, Repository};
let directory = tempfile::tempdir()?;
let repo = Repository::init(
    ObjectFormat::Sha1,
    directory.path().join("r.git"),
    InitKind::Bare,
)?;
let id = repo.loose_objects().write_blob(b"listed\n")?;
let objects = repo.objects_with(PackLimits::default())?;
assert_eq!(objects.object_ids(ListLimits::default())?, [id]);

pub fn object_ids_controlled( &self, limits: ListLimits, cancelled: &AtomicBool, ) -> Result<Vec<ObjectId>, ObjectReadError>

Collects every visible identity as Self::object_ids does, checking cancelled between directory entries.

Packed identities and loose directory entries both charge ListLimits::max_entries. The loose scan has the live semantics of ObjectStore::loose_objects.

Errors

Returns ObjectReadError::Limit when the entry budget runs out, ObjectReadError::Cancelled, or a loose directory I/O error with its path.

impl Objects

pub fn prefix_matches( &self, prefix: ObjectIdPrefix, ) -> Result<Vec<ObjectId>, ObjectReadError>

Finds all distinct stored identities matching a prefix, in ascending order.

Searches loose filenames and pinned pack indexes in the primary store and alternates. New loose files are visible; new packs require Self::refresh. Payloads are not decoded or hash-verified, and unindexed packs are ignored, just as for ordinary object lookup.

Errors

Reports format mismatch, directory I/O, or a changed/truncated pinned index.

pub fn resolve_prefix( &self, prefix: ObjectIdPrefix, ) -> Result<ObjectId, ResolvePrefixError>

Resolves a prefix to exactly one stored identity, independently of revision syntax.

Errors

Returns ResolvePrefixError::Missing for no match and ResolvePrefixError::Ambiguous with every candidate for multiple matches. Storage and format errors are preserved as ResolvePrefixError::Read.

use girt::{InitKind, ObjectFormat, ObjectIdPrefix, PackLimits, Repository};
let dir = tempfile::tempdir()?;
let repo = Repository::init(ObjectFormat::Sha1, dir.path().join("repo"), InitKind::Bare)?;
let id = repo.loose_objects().write_blob(b"hello")?;
let objects = repo.objects_with(PackLimits::default())?;
let prefix = ObjectIdPrefix::from_hex(repo.object_format(), "b6fc4")?;
assert_eq!(objects.resolve_prefix(prefix)?, id);
assert_eq!(objects.abbreviate(id, 4)?.to_string(), "b6fc");

Examples found in repository

examples/short_ids.rs (line 14)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut args = std::env::args().skip(1);
    let path = args
        .next()
        .ok_or("usage: short_ids <repository> <hex-prefix>")?;
    let text = args.next().ok_or("missing hexadecimal prefix")?;

    let repository = Repository::discover(path)?;
    let objects = repository.objects()?;

    let prefix = ObjectIdPrefix::from_hex(repository.object_format(), &text)?;
    let id = objects.resolve_prefix(prefix)?;
    println!("{}", objects.abbreviate(id, objects.auto_abbrev_len())?);
    Ok(())
}

pub fn abbreviate( &self, id: ObjectId, min_len: usize, ) -> Result<ObjectIdPrefix, ObjectReadError>

Finds the shortest prefix distinguishing id from all other stored identities.

Clamps min_len to four through the full format width. The ID need not exist (for example, a diff’s null sentinel); uniqueness is relative to the current storage view. Retain this reader across calls to reuse pack indexes and lazy loose-directory snapshots. Each loose bucket is scanned on its first abbreviation and retained until Self::refresh; clones share these snapshots. Prefix resolution remains live. Concurrent writes can invalidate uniqueness, so refresh before abbreviating against newly written objects.

Errors

Reports format mismatch or storage inspection failure, as Self::prefix_matches does.

Examples found in repository

examples/short_ids.rs (line 15)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut args = std::env::args().skip(1);
    let path = args
        .next()
        .ok_or("usage: short_ids <repository> <hex-prefix>")?;
    let text = args.next().ok_or("missing hexadecimal prefix")?;

    let repository = Repository::discover(path)?;
    let objects = repository.objects()?;

    let prefix = ObjectIdPrefix::from_hex(repository.object_format(), &text)?;
    let id = objects.resolve_prefix(prefix)?;
    println!("{}", objects.abbreviate(id, objects.auto_abbrev_len())?);
    Ok(())
}

pub fn auto_abbrev_len(&self) -> usize

Computes Git’s automatic minimum abbreviation length from the packed object count.

The estimate counts entries in each pinned pack, including duplicate copies and alternates. Loose objects do not increase this estimate. The minimum is seven; each additional digit provides four bits of space for the birthday-bound estimate. Call once per output operation, then pass the result to Self::abbreviate to lengthen actual collisions.

Examples found in repository

examples/short_ids.rs (line 15)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut args = std::env::args().skip(1);
    let path = args
        .next()
        .ok_or("usage: short_ids <repository> <hex-prefix>")?;
    let text = args.next().ok_or("missing hexadecimal prefix")?;

    let repository = Repository::discover(path)?;
    let objects = repository.objects()?;

    let prefix = ObjectIdPrefix::from_hex(repository.object_format(), &text)?;
    let id = objects.resolve_prefix(prefix)?;
    println!("{}", objects.abbreviate(id, objects.auto_abbrev_len())?);
    Ok(())
}

impl Objects

pub fn read_commit_with( &self, id: ObjectId, limits: ReadLimits, ) -> Result<Commit, ReadCommitError>

Reads and parses the commit id.

Use this when id came from a reference or a history walk and must be a commit. Unlike Self::read, a missing object is an error, because a commit you were pointed at should exist. Use Self::read to test whether an object exists or to accept any kind.

use girt::{
    Commit, CommitFields, InitKind, ObjectFormat, PackLimits, ReadLimits, Repository,
    Signature, Tree,
};

let directory = tempfile::tempdir()?;
let path = directory.path().join("repo.git");
let repository = Repository::init(ObjectFormat::Sha1, path, InitKind::Bare)?;

let loose = repository.loose_objects();
let tree = loose.write_tree(&Tree::new(ObjectFormat::Sha1, vec![])?)?;

let person = Signature {
    name: b"A. Writer".to_vec(),
    email: b"writer@example.com".to_vec(),
    seconds: 1_700_000_000,
    offset_minutes: 0,
};
let id = loose.write_commit(&Commit::new(CommitFields {
    tree,
    parents: vec![],
    author: person.clone(),
    committer: person,
    extra_headers: vec![],
    message: b"first\n".to_vec(),
})?)?;

let objects = repository.objects_with(PackLimits::default())?;
let commit = objects.read_commit_with(id, ReadLimits::default())?;
assert_eq!(commit.message(), b"first\n");
assert!(
    objects
        .read_commit_with(tree, ReadLimits::default())
        .is_err()
);

Errors

Returns ReadCommitError::Missing if no store has id, ReadCommitError::Kind if id names another kind of object, ReadCommitError::Parse for a malformed commit, and ReadCommitError::Read for the failures of Self::read.

pub fn read_commit(&self, id: ObjectId) -> Result<Commit, ReadCommitError>

Reads and parses the commit id with ReadLimits::default.

Equivalent to self.read_commit_with(id, ReadLimits::default()); see Self::read_commit_with.

Errors

Returns the errors of Self::read_commit_with.

pub fn read_tree_with( &self, id: ObjectId, limits: ReadLimits, ) -> Result<Tree, ReadTreeError>

Reads and parses the tree id.

Use this for a commit’s Commit::tree or a tree entry with crate::EntryMode::Tree. A missing object is an error, as with Self::read_commit. The canonical empty tree is present in every repository, as Self::read reports it.

use girt::{EntryMode, InitKind, ObjectFormat, ReadLimits, Repository, Tree, TreeEntry};

let directory = tempfile::tempdir()?;
let path = directory.path().join("repo.git");
let repository = Repository::init(ObjectFormat::Sha1, path, InitKind::Bare)?;

let loose = repository.loose_objects();
let blob = loose.write_blob(b"hello\n")?;
let entry = TreeEntry {
    name: b"hello.txt".to_vec(),
    mode: EntryMode::Blob,
    id: blob,
};
let id = loose.write_tree(&Tree::new(ObjectFormat::Sha1, vec![entry])?)?;

let objects = repository.objects()?;
let tree = objects.read_tree_with(id, ReadLimits::default())?;
assert_eq!(tree.entries()[0].name, b"hello.txt");
assert_eq!(objects.read_blob(tree.entries()[0].id)?, b"hello\n");
assert!(objects.read_tree(blob).is_err());

Errors

Returns ReadTreeError::Missing if no store has id, ReadTreeError::Kind if id names another kind of object, ReadTreeError::Parse for a malformed tree, and ReadTreeError::Read for the failures of Self::read.

pub fn read_tree(&self, id: ObjectId) -> Result<Tree, ReadTreeError>

Reads and parses the tree id with ReadLimits::default.

Equivalent to self.read_tree_with(id, ReadLimits::default()); see Self::read_tree_with.

Errors

Returns the errors of Self::read_tree_with.

pub fn read_tag_with( &self, id: ObjectId, limits: ReadLimits, ) -> Result<Tag, ReadTagError>

Reads and parses the annotated tag id.

A missing object is an error, as with Self::read_commit. Lightweight tags are references, not tag objects; resolve them through crate::refs.

use girt::{InitKind, ObjectFormat, ObjectKind, ReadLimits, Repository, Tag, TagFields};

let directory = tempfile::tempdir()?;
let path = directory.path().join("repo.git");
let repository = Repository::init(ObjectFormat::Sha1, path, InitKind::Bare)?;

let loose = repository.loose_objects();
let blob = loose.write_blob(b"release notes\n")?;
let id = loose.write_tag(&Tag::new(TagFields {
    target: blob,
    target_kind: ObjectKind::Blob,
    name: b"v1.0".to_vec(),
    tagger: None,
    extra_headers: vec![],
    message: b"first release\n".to_vec(),
})?)?;

let objects = repository.objects()?;
let tag = objects.read_tag_with(id, ReadLimits::default())?;
assert_eq!(tag.name(), b"v1.0");
assert_eq!(objects.read_tag(id)?.target(), blob);

Errors

Returns ReadTagError::Missing if no store has id, ReadTagError::Kind if id names another kind of object, ReadTagError::Parse for a malformed tag, and ReadTagError::Read for the failures of Self::read.

pub fn read_tag(&self, id: ObjectId) -> Result<Tag, ReadTagError>

Reads and parses the annotated tag id with ReadLimits::default.

Equivalent to self.read_tag_with(id, ReadLimits::default()); see Self::read_tag_with.

Errors

Returns the errors of Self::read_tag_with.

pub fn read_blob_with( &self, id: ObjectId, limits: ReadLimits, ) -> Result<Vec<u8>, ReadBlobError>

Reads the blob id and returns its bytes.

Blob bytes need no parsing. A missing object is an error, as with Self::read_commit. The bytes are copied out of the reader’s delta base cache when it shares them; borrow Object::data from Self::read to avoid that copy. See Self::read_tree_with for an example.

Errors

Returns ReadBlobError::Missing if no store has id, ReadBlobError::Kind if id names another kind of object, and ReadBlobError::Read for the failures of Self::read.

pub fn read_blob(&self, id: ObjectId) -> Result<Vec<u8>, ReadBlobError>

Reads the blob id with ReadLimits::default and returns its bytes.

Equivalent to self.read_blob_with(id, ReadLimits::default()); see Self::read_blob_with. The default limits refuse blobs over 64 MiB; pass larger ReadLimits to Self::read_blob_with when the repository is trusted to hold them.

Errors

Returns the errors of Self::read_blob_with.

Examples found in repository

examples/open_repository.rs (line 21)

fn main() -> girt::Result<()> {
    let args = Args::parse();
    let git = Repo::new(Repository::open(args.path)?);
    let id = git.rev_parse(&args.revision)?;
    let bytes = git.repository().objects()?.read_blob(id)?;
    println!(
        "Read {} bytes from {}",
        bytes.len(),
        git.repository().object_dir().display()
    );
    Ok(())
}

impl Objects

pub fn store_directories(&self) -> impl Iterator<Item = &Path>

Returns canonical object directories in search order, primary first.

Subsequent entries are alternates owned outside this repository. A maintenance planner must never treat their contents as owned pruning candidates.

pub fn shallow_roots(&self) -> &ShallowRoots

Fixed history boundaries inherited from the repository handle, unaffected by later refresh.

pub fn object_format(&self) -> ObjectFormat

Format shared by all objects in this store.

pub fn refresh( &mut self, packs: PackLimits, alternates: AlternateLimits, ) -> Result<(), ObjectReadError>

Replaces this reader’s pack and alternate view after one successful bounded scan. Also clears lazy loose-directory snapshots used by Self::abbreviate.

Rediscover from the original canonical primary directory using the supplied aggregate limits. Newly installed indexed packs and alternate topology become visible; removed packs disappear from this reader. Clones retain their previous pinned pairs and topology until they refresh or drop. Loose paths remain live in every reader, so an old reader can lose loose-only objects after GC or observe new loose objects without refresh. Shallow roots remain unchanged; refresh the repository’s shallow snapshot separately when needed.

Every pair is reopened and revalidated, even if its filename is unchanged. The old and new views coexist until success: peak handles and tables can reach their combined limits, multiplied by independently retained generations. Clone shares handles within a generation. Like crate::Repository::objects, refresh validates index structure and pack headers/trailers without hashing indexes or scanning pack bodies. Use Self::verify_packs for index checksum, whole-pack checksum and CRC proof.

Errors

Returns opening errors without changing this reader or its clones. An index whose pack is absent, a mismatched pair, malformed alternate metadata or corrupt index/header is an error, never absence. Pack body corruption is deferred to reads or explicit verification. There are no automatic retries, sleeps or filesystem changes. After a publisher finishes or a broken pair is repaired/removed, the caller may explicitly retry with its own finite attempt budget. Continuing publication may require another refresh even after success: directory enumeration and alternate discovery are not atomic snapshots.

use girt::{
    AlternateLimits, InitKind, ObjectFormat, ObjectId, ObjectKind, PackLimits, PackObject,
    PackWriteLimits, ReadLimits, Repository, write_pack,
};

let directory = tempfile::tempdir()?;
let repo = Repository::init(
    ObjectFormat::Sha1,
    directory.path().join("r.git"),
    InitKind::Bare,
)?;

let mut objects = repo.objects_with(PackLimits::default())?;
let retained = objects.clone();

let data = b"published only in a new pack";
let id = ObjectId::for_blob(ObjectFormat::Sha1, data);
let input = PackObject {
    id,
    kind: ObjectKind::Blob,
    data,
};

let (mut pack, mut index) = (Vec::new(), Vec::new());
let written = write_pack(
    ObjectFormat::Sha1,
    &[input],
    &mut pack,
    &mut index,
    PackWriteLimits::default(),
)?;

let base = repo
    .object_dir()
    .join("pack")
    .join(format!("pack-{}", written.checksum));
// Private fixture only: shared installation requires a coordinated publication path.
std::fs::write(base.with_extension("pack"), pack)?;
std::fs::write(base.with_extension("idx"), index)?;

assert!(objects.read_with(id, ReadLimits::default())?.is_none());
objects.refresh(PackLimits::default(), AlternateLimits::default())?;
assert_eq!(
    objects
        .read_with(id, ReadLimits::default())?
        .ok_or("missing")?
        .data(),
    data
);

// The clone retains the old generation.
assert!(retained.read_with(id, ReadLimits::default())?.is_none());

Examples found in repository

examples/store_open.rs (line 46)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let args = Args::parse();
    let operation = args.operation;

    let start = Instant::now();
    let repository = Repository::open(args.path)?;
    let head = repository.head()?.id.ok_or("unborn HEAD")?;

    let count = if operation == Operation::Repeat { 8 } else { 1 };
    for _ in 0..count {
        let mut objects = repository.objects_with(PackLimits::trusted())?;
        let measured = Instant::now();

        match operation {
            Operation::Refresh => {
                objects.refresh(PackLimits::trusted(), AlternateLimits::default())?
            }
            Operation::Open | Operation::Repeat => {}
            Operation::Verify => objects.verify_packs(&AtomicBool::new(false))?,
        }

        let object = objects
            .read_with(head, ReadLimits::trusted())?
            .ok_or("missing HEAD")?;
        std::hint::black_box(object);

        if operation == Operation::Refresh {
            println!("refresh_seconds={:.9}", measured.elapsed().as_secs_f64());
        }
    }

    println!("total_seconds={:.9}", start.elapsed().as_secs_f64());
    Ok(())
}

examples/storage_resources.rs (lines 100-103)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let args = Args::parse();
    let repository = Repository::open(args.repository)?;
    let id = args.id;

    let baseline = handles();
    let failed = repository.objects_with(PackLimits::default().with_max_index_bytes(0));
    assert!(matches!(
        failed,
        Err(girt::ObjectReadError::Limit("pack index bytes"))
    ));
    assert_eq!(handles(), baseline);

    if args.mode == Some(Mode::Cancel) {
        let cancelled = AtomicBool::new(false);
        let start = Instant::now();

        let result = std::thread::scope(|scope| {
            scope.spawn(|| {
                std::thread::sleep(Duration::from_millis(10));
                cancelled.store(true, std::sync::atomic::Ordering::Relaxed);
            });
            repository.objects_controlled(
                PackLimits::default(),
                AlternateLimits::default(),
                &cancelled,
            )
        });

        assert!(matches!(result, Err(girt::ObjectReadError::Cancelled)));
        assert_eq!(handles(), baseline);

        println!(
            "cancel_us={} handles_before={baseline:?} handles_after={:?}",
            start.elapsed().as_micros(),
            handles()
        );
        return Ok(());
    }

    let cancelled = AtomicBool::new(false);
    let start = Instant::now();
    let mut objects = repository.objects_controlled(
        PackLimits::default(),
        AlternateLimits::default(),
        &cancelled,
    )?;

    let opened = start.elapsed();
    let retained = handles();
    let clone = objects.clone();
    let cloned = handles();

    let failed = objects.refresh(
        PackLimits::default().with_max_index_bytes(0),
        AlternateLimits::default(),
    );
    assert!(matches!(
        failed,
        Err(girt::ObjectReadError::Limit("pack index bytes"))
    ));
    assert_eq!(handles(), cloned);

    let start = Instant::now();
    objects.refresh(PackLimits::default(), AlternateLimits::default())?;
    let refreshed = start.elapsed();

    let generations = handles();
    assert_eq!(
        generations,
        baseline
            .zip(retained)
            .map(|(base, open)| base + 2 * (open - base))
    );

    println!(
        "refresh_us={} handles_two_generations={generations:?}",
        refreshed.as_micros()
    );

    let start = Instant::now();
    let object = clone
        .read_controlled(id, ReadLimits::default(), &cancelled)?
        .ok_or("object missing")?;
    let read = start.elapsed();

    let start = Instant::now();
    let second = clone
        .read_with(id, ReadLimits::default())?
        .ok_or("object missing")?;
    let reread = start.elapsed();

    assert_eq!(object, second);
    println!(
        "pid={} open_us={} first_read_us={} warm_read_us={} payload_bytes={} handles_before={baseline:?} handles_open={retained:?} handles_clone={cloned:?}",
        std::process::id(),
        opened.as_micros(),
        read.as_micros(),
        reread.as_micros(),
        object.data().len()
    );

    drop(second);
    drop(object);
    drop(objects);
    drop(clone);

    println!("handles_after_drop={:?}", handles());
    assert_eq!(handles(), baseline);

    // Optional sampling interval is outside measured operations and retains no reader.
    if args.mode == Some(Mode::Hold) {
        std::thread::sleep(Duration::from_secs(1));
    }
    Ok(())
}

pub fn refresh_controlled( &mut self, packs: PackLimits, alternates: AlternateLimits, cancelled: &AtomicBool, ) -> Result<(), ObjectReadError>

Refreshes with the same cooperative cancellation checkpoints as opening.

Cancellation before replacing the view releases all candidate handles and preserves the current view. Blocking OS calls cannot be interrupted. See Self::refresh for resource, publication, retained-reader and explicit retry contracts.

Errors

Returns the errors from Self::refresh or ObjectReadError::Cancelled.

pub fn verify_packs( &self, cancelled: &AtomicBool, ) -> Result<(), ObjectReadError>

Verifies index checksums, whole-pack checksums and v2 entry CRCs in every pinned store, including alternates.

Opening checks index structure, pack framing and trailer agreement without hashing the index or reading pack bodies. Use this operation when the complete raw-byte checksum proof is required. It streams each pack with bounded scratch memory and checks cancellation every 64 KiB. The artifact sizes already charged to PackLimits::max_bytes bound this work. It changes no files or reader state; failure and cancellation leave the reader usable for unaffected objects.

This is not a full fsck: it does not decode objects, verify their identities, validate payload syntax or check connectivity. Legacy v1 indexes have no entry CRCs. Artifacts must remain immutable throughout verification, as throughout this reader’s lifetime.

Errors

Returns checksum/CRC corruption, artifact I/O errors or ObjectReadError::Cancelled. Also refuses packed damage remembered by prior reads, including identity-only failures; that contextual error retains the path, offset and original corruption cause.

use girt::{ObjectFormat, ObjectId, ObjectKind, PackObject, PackWriteLimits, write_pack};
let input = PackObject {
    id: ObjectId::for_blob(ObjectFormat::Sha1, b"manifest"),
    kind: ObjectKind::Blob,
    data: b"manifest",
};

let (mut bytes, mut index) = (Vec::new(), Vec::new());
let written = write_pack(
    ObjectFormat::Sha1,
    &[input],
    &mut bytes,
    &mut index,
    PackWriteLimits::default(),
)?;

let directory = tempfile::tempdir()?;
let repo = girt::Repository::init(
    ObjectFormat::Sha1,
    directory.path().join("r.git"),
    girt::InitKind::Bare,
)?;

let base = repo
    .object_dir()
    .join("pack")
    .join(format!("pack-{}", written.checksum));
// Private fixture only; shared repositories need a validated installation path.
std::fs::write(base.with_extension("pack"), bytes)?;
std::fs::write(base.with_extension("idx"), index)?;

let objects = repo.objects_with(girt::PackLimits::default())?;
objects.verify_packs(&std::sync::atomic::AtomicBool::new(false))?;
assert!(
    objects
        .read_with(input.id, girt::ReadLimits::default())?
        .is_some()
);

Examples found in repository

examples/store_open.rs (line 49)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let args = Args::parse();
    let operation = args.operation;

    let start = Instant::now();
    let repository = Repository::open(args.path)?;
    let head = repository.head()?.id.ok_or("unborn HEAD")?;

    let count = if operation == Operation::Repeat { 8 } else { 1 };
    for _ in 0..count {
        let mut objects = repository.objects_with(PackLimits::trusted())?;
        let measured = Instant::now();

        match operation {
            Operation::Refresh => {
                objects.refresh(PackLimits::trusted(), AlternateLimits::default())?
            }
            Operation::Open | Operation::Repeat => {}
            Operation::Verify => objects.verify_packs(&AtomicBool::new(false))?,
        }

        let object = objects
            .read_with(head, ReadLimits::trusted())?
            .ok_or("missing HEAD")?;
        std::hint::black_box(object);

        if operation == Operation::Refresh {
            println!("refresh_seconds={:.9}", measured.elapsed().as_secs_f64());
        }
    }

    println!("total_seconds={:.9}", start.elapsed().as_secs_f64());
    Ok(())
}

pub fn read_with( &self, id: ObjectId, limits: ReadLimits, ) -> Result<Option<Object>, ObjectReadError>

Reads an exact object by full identity in this store’s format; returns None only when absent.

The payload is uninterpreted. Parse it separately if structured fields are needed. Searches each store’s pinned packs in filename order, then its live loose files, primary before alternates. Packed corruption retries remaining copies with full identity checks. Failed packed entries are remembered for this handle and its clones; refresh preserves evidence for the same artifacts. Reads never refresh storage implicitly.

Errors

Returns storage errors for corrupt/unsupported objects, I/O failures, missing delta bases, cycles, incompatible identity formats, or exhausted resource limits. An invalid loose object fails immediately unless this read is already retrying packed corruption. If all copies are absent or damaged after a packed failure, the error names that pack; its source chain includes the entry offset and concrete corruption cause. Packed damage uses ObjectReadError::Path with an InvalidData I/O source. Cancellation, resource limits, unsupported headers, missing/external delta bases and ordinary I/O failures do not mark entries bad or trigger fallback. Only the first packed corruption cause is reported, including when a later loose copy is also corrupt. No filesystem changes occur.

use girt::{InitKind, ObjectFormat, PackLimits, ReadLimits, Repository};

let directory = tempfile::tempdir()?;
let repo = Repository::init(
    ObjectFormat::Sha1,
    directory.path().join("r.git"),
    InitKind::Bare,
)?;

let id = repo.loose_objects().write_blob(b"payload\n")?;
let objects = repo.objects_with(PackLimits::default())?;
let limits = ReadLimits::default().with_max_object_bytes(1024);
assert_eq!(
    objects.read_with(id, limits)?.ok_or("missing blob")?.data(),
    b"payload\n"
);

let absent = girt::ObjectId::for_blob(ObjectFormat::Sha1, b"not written");
assert!(objects.read_with(absent, limits)?.is_none());

Examples found in repository

examples/store_open.rs (line 53)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let args = Args::parse();
    let operation = args.operation;

    let start = Instant::now();
    let repository = Repository::open(args.path)?;
    let head = repository.head()?.id.ok_or("unborn HEAD")?;

    let count = if operation == Operation::Repeat { 8 } else { 1 };
    for _ in 0..count {
        let mut objects = repository.objects_with(PackLimits::trusted())?;
        let measured = Instant::now();

        match operation {
            Operation::Refresh => {
                objects.refresh(PackLimits::trusted(), AlternateLimits::default())?
            }
            Operation::Open | Operation::Repeat => {}
            Operation::Verify => objects.verify_packs(&AtomicBool::new(false))?,
        }

        let object = objects
            .read_with(head, ReadLimits::trusted())?
            .ok_or("missing HEAD")?;
        std::hint::black_box(object);

        if operation == Operation::Refresh {
            println!("refresh_seconds={:.9}", measured.elapsed().as_secs_f64());
        }
    }

    println!("total_seconds={:.9}", start.elapsed().as_secs_f64());
    Ok(())
}

examples/storage_resources.rs (line 135)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let args = Args::parse();
    let repository = Repository::open(args.repository)?;
    let id = args.id;

    let baseline = handles();
    let failed = repository.objects_with(PackLimits::default().with_max_index_bytes(0));
    assert!(matches!(
        failed,
        Err(girt::ObjectReadError::Limit("pack index bytes"))
    ));
    assert_eq!(handles(), baseline);

    if args.mode == Some(Mode::Cancel) {
        let cancelled = AtomicBool::new(false);
        let start = Instant::now();

        let result = std::thread::scope(|scope| {
            scope.spawn(|| {
                std::thread::sleep(Duration::from_millis(10));
                cancelled.store(true, std::sync::atomic::Ordering::Relaxed);
            });
            repository.objects_controlled(
                PackLimits::default(),
                AlternateLimits::default(),
                &cancelled,
            )
        });

        assert!(matches!(result, Err(girt::ObjectReadError::Cancelled)));
        assert_eq!(handles(), baseline);

        println!(
            "cancel_us={} handles_before={baseline:?} handles_after={:?}",
            start.elapsed().as_micros(),
            handles()
        );
        return Ok(());
    }

    let cancelled = AtomicBool::new(false);
    let start = Instant::now();
    let mut objects = repository.objects_controlled(
        PackLimits::default(),
        AlternateLimits::default(),
        &cancelled,
    )?;

    let opened = start.elapsed();
    let retained = handles();
    let clone = objects.clone();
    let cloned = handles();

    let failed = objects.refresh(
        PackLimits::default().with_max_index_bytes(0),
        AlternateLimits::default(),
    );
    assert!(matches!(
        failed,
        Err(girt::ObjectReadError::Limit("pack index bytes"))
    ));
    assert_eq!(handles(), cloned);

    let start = Instant::now();
    objects.refresh(PackLimits::default(), AlternateLimits::default())?;
    let refreshed = start.elapsed();

    let generations = handles();
    assert_eq!(
        generations,
        baseline
            .zip(retained)
            .map(|(base, open)| base + 2 * (open - base))
    );

    println!(
        "refresh_us={} handles_two_generations={generations:?}",
        refreshed.as_micros()
    );

    let start = Instant::now();
    let object = clone
        .read_controlled(id, ReadLimits::default(), &cancelled)?
        .ok_or("object missing")?;
    let read = start.elapsed();

    let start = Instant::now();
    let second = clone
        .read_with(id, ReadLimits::default())?
        .ok_or("object missing")?;
    let reread = start.elapsed();

    assert_eq!(object, second);
    println!(
        "pid={} open_us={} first_read_us={} warm_read_us={} payload_bytes={} handles_before={baseline:?} handles_open={retained:?} handles_clone={cloned:?}",
        std::process::id(),
        opened.as_micros(),
        read.as_micros(),
        reread.as_micros(),
        object.data().len()
    );

    drop(second);
    drop(object);
    drop(objects);
    drop(clone);

    println!("handles_after_drop={:?}", handles());
    assert_eq!(handles(), baseline);

    // Optional sampling interval is outside measured operations and retains no reader.
    if args.mode == Some(Mode::Hold) {
        std::thread::sleep(Duration::from_secs(1));
    }
    Ok(())
}

pub fn contains(&self, id: ObjectId) -> Result<bool, ObjectReadError>

Reports whether this snapshot holds id, without reading or verifying the stored copy.

Searches the same stores in the same order as Self::read: each store’s pinned pack indexes, then its live loose files, primary before alternates. The canonical empty tree is always present, as in Self::read. A pack published after this snapshot was taken is not seen, so a false can be out of date; Self::refresh picks up new packs.

Use this to skip storing content the repository already has, as Git does when it writes an object that is already packed. A true is the store’s claim, not proof that the copy decodes: Self::read verifies identity and reports a damaged copy when the object is read.

Errors

Returns ObjectReadError::Loose wrapping a format error for a foreign-format id, and storage errors when a pack index or loose object directory cannot be read. A missing loose file is absence, not an error. No filesystem changes occur.

use girt::{InitKind, ObjectFormat, ObjectId, PackLimits, Repository};

let directory = tempfile::tempdir()?;
let repo = Repository::init(
    ObjectFormat::Sha1,
    directory.path().join("r.git"),
    InitKind::Bare,
)?;
let stored = repo.loose_objects().write_blob(b"payload\n")?;
let objects = repo.objects_with(PackLimits::default())?;
assert!(objects.contains(stored)?);

// Hash first, then store only what the repository lacks.
let content = b"new content\n";
let id = ObjectId::for_blob(ObjectFormat::Sha1, content);
assert!(!objects.contains(id)?);
assert_eq!(repo.loose_objects().write_blob(content)?, id);
assert!(objects.contains(id)?);

Examples found in repository

examples/midx_lookup_timing.rs (line 50)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut args = std::env::args().skip(1);
    let path = args.next().ok_or("expected repository path")?;
    let list = args.next().ok_or("expected object-ID list path")?;
    let rounds: usize = args.next().ok_or("expected number of rounds")?.parse()?;
    let mode = args.next().unwrap_or_else(|| "read".to_owned());
    let ids = std::fs::read_to_string(list)?
        .lines()
        .map(str::parse)
        .collect::<Result<Vec<ObjectId>, _>>()?;
    let repo = Repository::open(path)?;
    let start = Instant::now();
    let objects = repo.objects()?;
    let opening = start.elapsed();
    let packs: Vec<_> = objects.packs().collect();
    let bytes = if mode == "midx" {
        std::fs::read(repo.object_dir().join("pack/multi-pack-index"))?
    } else {
        Vec::new()
    };
    let midx = if mode == "midx" {
        Some(girt::multi_pack_index::MultiPackIndex::parse(
            &bytes,
            repo.object_format(),
        )?)
    } else {
        None
    };
    let start = Instant::now();
    let mut found = 0_usize;
    for _ in 0..rounds {
        for id in &ids {
            let present = match mode.as_str() {
                "read" => {
                    black_box(objects.read(*id)?.ok_or("object absent")?);
                    true
                }
                "contains" => objects.contains(*id)?,
                "index-scan" => scan(&packs, *id)?,
                "midx" => midx.as_ref().ok_or("index absent")?.find(*id).is_some(),
                _ => return Err("expected read, contains, index-scan or midx".into()),
            };
            found += usize::from(black_box(present));
        }
    }
    println!(
        "objects={} rounds={rounds} mode={mode} found={found} open_ns={} read_ns={}",
        ids.len(),
        opening.as_nanos(),
        start.elapsed().as_nanos(),
    );
    Ok(())
}

pub fn read(&self, id: ObjectId) -> Result<Option<Object>, ObjectReadError>

Reads an exact object by full identity with ReadLimits::default; returns None only when absent.

Equivalent to self.read_with(id, ReadLimits::default()); see Self::read_with for store precedence and damage handling. The default limits refuse payloads over 64 MiB. Use Self::read_commit, Self::read_tree, Self::read_tag or Self::read_blob when the kind is known.

Errors

Returns the errors of Self::read_with.

Examples found in repository

examples/packed_repository.rs (line 25)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let args = Args::parse();
    let repository = Repository::open(args.path)?;
    let objects = repository.objects()?;
    let object = objects.read(args.id)?.ok_or("object absent")?;

    eprintln!(
        "{} {} ({} bytes)",
        object.kind().as_str(),
        object.id(),
        object.data().len()
    );
    io::stdout().write_all(object.data())?;
    Ok(())
}

examples/scheduling/fixture.rs (line 92)

    pub fn operation(&self, gate: Option<Gate>) {
        let repo = Repository::open(self.root.path()).unwrap();
        let objects = repo.objects().unwrap();

        if let Some(gate) = gate {
            gate.started.send(()).unwrap();
            gate.release.recv().unwrap();
        }

        let blob = objects.read(self.blob).unwrap().unwrap();
        assert_eq!(blob.data().len(), 2 * 1024 * 1024);
        assert_eq!(objects.walk(&[self.tip]).unwrap().len(), 512);
    }

examples/write_pack.rs (line 49)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let root = tempfile::tempdir()?;
    let format = girt::ObjectFormat::Sha256;
    let payload = b"explicit export\0\xff";
    let id = ObjectId::for_blob(format, payload);

    let inputs = [PackObject {
        id,
        kind: ObjectKind::Blob,
        data: payload,
    }];

    let mut pack = BufWriter::new(File::create(root.path().join("export.pack"))?);
    let mut index = BufWriter::new(File::create(root.path().join("export.idx"))?);
    let written = write_pack(
        format,
        &inputs,
        &mut pack,
        &mut index,
        PackWriteLimits::default(),
    )?;

    pack.flush()?;
    index.flush()?;
    drop((pack, index));

    // Only this example owns the new repository. Prepare both files before opening any readers.
    // A live repository needs a separate safe publication protocol, not this two-rename sequence.
    let repo_path = root.path().join("private.git");
    let repo = Repository::init(format, &repo_path, girt::InitKind::Bare)?;

    let basename = format!("objects/pack/pack-{}", written.checksum);
    fs::rename(
        root.path().join("export.pack"),
        repo_path.join(format!("{basename}.pack")),
    )?;
    fs::rename(
        root.path().join("export.idx"),
        repo_path.join(format!("{basename}.idx")),
    )?;

    let objects = repo.objects()?;
    let restored = objects.read(id)?.ok_or("exported object missing")?;
    assert_eq!(restored.kind(), ObjectKind::Blob);
    assert_eq!(restored.data(), payload);

    println!(
        "Verified {} explicit object in {} pack bytes and {} index bytes",
        written.objects, written.pack_bytes, written.index_bytes
    );
    Ok(())
}

examples/midx_lookup_timing.rs (line 47)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut args = std::env::args().skip(1);
    let path = args.next().ok_or("expected repository path")?;
    let list = args.next().ok_or("expected object-ID list path")?;
    let rounds: usize = args.next().ok_or("expected number of rounds")?.parse()?;
    let mode = args.next().unwrap_or_else(|| "read".to_owned());
    let ids = std::fs::read_to_string(list)?
        .lines()
        .map(str::parse)
        .collect::<Result<Vec<ObjectId>, _>>()?;
    let repo = Repository::open(path)?;
    let start = Instant::now();
    let objects = repo.objects()?;
    let opening = start.elapsed();
    let packs: Vec<_> = objects.packs().collect();
    let bytes = if mode == "midx" {
        std::fs::read(repo.object_dir().join("pack/multi-pack-index"))?
    } else {
        Vec::new()
    };
    let midx = if mode == "midx" {
        Some(girt::multi_pack_index::MultiPackIndex::parse(
            &bytes,
            repo.object_format(),
        )?)
    } else {
        None
    };
    let start = Instant::now();
    let mut found = 0_usize;
    for _ in 0..rounds {
        for id in &ids {
            let present = match mode.as_str() {
                "read" => {
                    black_box(objects.read(*id)?.ok_or("object absent")?);
                    true
                }
                "contains" => objects.contains(*id)?,
                "index-scan" => scan(&packs, *id)?,
                "midx" => midx.as_ref().ok_or("index absent")?.find(*id).is_some(),
                _ => return Err("expected read, contains, index-scan or midx".into()),
            };
            found += usize::from(black_box(present));
        }
    }
    println!(
        "objects={} rounds={rounds} mode={mode} found={found} open_ns={} read_ns={}",
        ids.len(),
        opening.as_nanos(),
        start.elapsed().as_nanos(),
    );
    Ok(())
}

examples/fetch_local.rs (line 82)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let (_source_root, source) = repository()?;
    let (_destination_root, destination) = repository()?;

    let objects = source.loose_objects();
    let blob = objects.write_blob(b"Fetched through native local storage\n")?;
    let tree = objects.write_tree(&Tree::new(
        girt::ObjectFormat::Sha1,
        vec![TreeEntry {
            mode: EntryMode::Blob,
            name: b"hello.txt".to_vec(),
            id: blob,
        }],
    )?)?;

    let author = Signature::now(b"Fetch Example", b"fetch@example.com")?;
    let commit = objects.write_commit(&Commit::new(CommitFields {
        tree,
        parents: vec![],
        author: author.clone(),
        committer: author,
        extra_headers: vec![],
        message: b"Local fetch fixture\n".to_vec(),
    })?)?;

    let branch = RefName::branch("main")?;
    source.references()?.update_without_reflog(
        &branch,
        Target::Direct(commit),
        Expected::Absent,
    )?;

    let cancel = AtomicBool::new(false);
    let received = receive_local(
        source.git_dir(),
        |advertisement| {
            advertisement
                .refs
                .iter()
                .filter(|reference| {
                    reference.name == branch
                        && reference.kind == girt::fetch::AdvertisementKind::Tip
                })
                .map(|reference| reference.id)
                .collect()
        },
        girt::fetch::LocalFetchRequest::new(FetchLimits::default()),
        TransportControl::new(&cancel)
            .with_deadline(Some(Instant::now() + Duration::from_secs(30))),
        girt::fetch::LocalFetchObserver::default(),
    )?;

    let result = received.install(&destination, girt::PackLimits::default(), &cancel)?;

    // Updating a ref is a separate, conditional operation, explicitly without a reflog.
    destination.references()?.update_without_reflog(
        &branch,
        Target::Direct(commit),
        Expected::Absent,
    )?;

    let fetched = destination.objects()?;
    let restored = fetched.read(blob)?.ok_or("missing fetched blob")?;
    assert_eq!(restored.data(), b"Fetched through native local storage\n");

    println!(
        "Fetched {} objects ({} pack bytes); published {commit} without a reflog",
        result.objects,
        received.pack_bytes()
    );

    let known = KnownHistory::new(&fetched, &[commit], FetchLimits::default(), &cancel)?;
    let repeated = receive_local(
        source.git_dir(),
        |_| vec![commit],
        girt::fetch::LocalFetchRequest::new(FetchLimits::default()).with_known(&known),
        TransportControl::new(&cancel)
            .with_deadline(Some(Instant::now() + Duration::from_secs(30))),
        girt::fetch::LocalFetchObserver::default(),
    )?;

    // Recheck known dependencies in the destination even when no pack was needed.
    repeated.install(&destination, girt::PackLimits::default(), &cancel)?;
    assert_eq!(repeated.pack_bytes(), 0);
    println!(
        "Repeated fetch: {} objects, {} pack bytes",
        repeated.object_count(),
        repeated.pack_bytes()
    );

    Ok(())
}

examples/push_local.rs (line 82)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let (_source_root, source) = repository()?;
    let (_destination_root, destination) = repository()?;

    let loose = source.loose_objects();
    let blob = loose.write_blob(b"Published by girt through native local storage\n")?;
    let tree = loose.write_tree(&Tree::new(
        girt::ObjectFormat::Sha1,
        vec![TreeEntry {
            mode: EntryMode::Blob,
            name: b"hello.txt".to_vec(),
            id: blob,
        }],
    )?)?;

    let author = Signature::now(b"Push Example", b"push@example.com")?;
    let commit = loose.write_commit(&Commit::new(CommitFields {
        tree,
        parents: vec![],
        author: author.clone(),
        committer: author.clone(),
        extra_headers: vec![],
        message: b"Local push fixture\n".to_vec(),
    })?)?;

    let tag = loose.write_tag(&Tag::new(TagFields {
        target: commit,
        target_kind: ObjectKind::Commit,
        name: b"v1".to_vec(),
        tagger: Some(author),
        extra_headers: vec![],
        message: b"First publication\n".to_vec(),
    })?)?;

    let cancel = AtomicBool::new(false);
    let objects = source.objects()?;
    let commands = vec![
        PushCommand::new(RefName::new("refs/heads/main")?, None, commit)
            .with_force(ForcePolicy::FastForwardOnly),
        PushCommand::new(RefName::new("refs/tags/v1")?, None, tag)
            .with_force(ForcePolicy::FastForwardOnly),
    ];
    let prepared = PreparedPush::new(&objects, commands, &[], PushLimits::default(), &cancel)?;

    let report = send_local(
        destination.git_dir(),
        girt::push::LocalPushRequest::new(&prepared),
        TransportControl::new(&cancel)
            .with_deadline(Some(Instant::now() + Duration::from_secs(30))),
        |_| {},
    )?;

    // A complete protocol exchange can still contain rejection or partial success.
    if !report.all_succeeded() {
        return Err(format!("native local push rejected updates: {report:?}").into());
    }

    let restored = destination
        .objects()?
        .read(blob)?
        .ok_or("missing pushed blob")?;
    assert_eq!(
        restored.data(),
        b"Published by girt through native local storage\n"
    );

    println!(
        "Published branch and annotated tag: {} objects, {} pack bytes",
        prepared.object_count(),
        prepared.pack_bytes()
    );

    let repeated = PreparedPush::new(
        &objects,
        vec![
            PushCommand::new(RefName::new("refs/heads/main")?, Some(commit), commit)
                .with_force(ForcePolicy::FastForwardOnly),
        ],
        &[commit],
        PushLimits::default(),
        &cancel,
    )?;

    let report = send_local(
        destination.git_dir(),
        girt::push::LocalPushRequest::new(&repeated),
        TransportControl::new(&cancel)
            .with_deadline(Some(Instant::now() + Duration::from_secs(30))),
        |_| {},
    )?;

    if !report.all_succeeded() {
        return Err(format!("repeat rejected: {report:?}").into());
    }
    assert_eq!(repeated.object_count(), 0);
    println!(
        "Repeated push: {} objects, {} pack bytes",
        repeated.object_count(),
        repeated.pack_bytes()
    );

    Ok(())
}

pub fn read_controlled( &self, id: ObjectId, limits: ReadLimits, cancelled: &AtomicBool, ) -> Result<Option<Object>, ObjectReadError>

Reads with cooperative cancellation between stores, pack lookups and decode chunks.

Loose reads, index lookups, object hashing and individual delta applications finish before the next checkpoint. Blocked filesystem calls cannot be interrupted. No partial object is returned; all per-read buffers are released when the call returns.

Errors

Returns the same storage errors as Self::read, or ObjectReadError::Cancelled.

use girt::{InitKind, ObjectFormat, PackLimits, ReadLimits, Repository};

let directory = tempfile::tempdir()?;
let repo = Repository::init(
    ObjectFormat::Sha1,
    directory.path().join("r.git"),
    InitKind::Bare,
)?;

let id = repo.loose_objects().write_blob(b"payload")?;
let objects = repo.objects_with(PackLimits::default())?;
let cancelled = std::sync::atomic::AtomicBool::new(true);
assert!(matches!(
    objects.read_controlled(id, ReadLimits::default(), &cancelled),
    Err(girt::ObjectReadError::Cancelled)
));

assert!(objects.read_with(id, ReadLimits::default())?.is_some());

Examples found in repository

examples/storage_resources.rs (line 129)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let args = Args::parse();
    let repository = Repository::open(args.repository)?;
    let id = args.id;

    let baseline = handles();
    let failed = repository.objects_with(PackLimits::default().with_max_index_bytes(0));
    assert!(matches!(
        failed,
        Err(girt::ObjectReadError::Limit("pack index bytes"))
    ));
    assert_eq!(handles(), baseline);

    if args.mode == Some(Mode::Cancel) {
        let cancelled = AtomicBool::new(false);
        let start = Instant::now();

        let result = std::thread::scope(|scope| {
            scope.spawn(|| {
                std::thread::sleep(Duration::from_millis(10));
                cancelled.store(true, std::sync::atomic::Ordering::Relaxed);
            });
            repository.objects_controlled(
                PackLimits::default(),
                AlternateLimits::default(),
                &cancelled,
            )
        });

        assert!(matches!(result, Err(girt::ObjectReadError::Cancelled)));
        assert_eq!(handles(), baseline);

        println!(
            "cancel_us={} handles_before={baseline:?} handles_after={:?}",
            start.elapsed().as_micros(),
            handles()
        );
        return Ok(());
    }

    let cancelled = AtomicBool::new(false);
    let start = Instant::now();
    let mut objects = repository.objects_controlled(
        PackLimits::default(),
        AlternateLimits::default(),
        &cancelled,
    )?;

    let opened = start.elapsed();
    let retained = handles();
    let clone = objects.clone();
    let cloned = handles();

    let failed = objects.refresh(
        PackLimits::default().with_max_index_bytes(0),
        AlternateLimits::default(),
    );
    assert!(matches!(
        failed,
        Err(girt::ObjectReadError::Limit("pack index bytes"))
    ));
    assert_eq!(handles(), cloned);

    let start = Instant::now();
    objects.refresh(PackLimits::default(), AlternateLimits::default())?;
    let refreshed = start.elapsed();

    let generations = handles();
    assert_eq!(
        generations,
        baseline
            .zip(retained)
            .map(|(base, open)| base + 2 * (open - base))
    );

    println!(
        "refresh_us={} handles_two_generations={generations:?}",
        refreshed.as_micros()
    );

    let start = Instant::now();
    let object = clone
        .read_controlled(id, ReadLimits::default(), &cancelled)?
        .ok_or("object missing")?;
    let read = start.elapsed();

    let start = Instant::now();
    let second = clone
        .read_with(id, ReadLimits::default())?
        .ok_or("object missing")?;
    let reread = start.elapsed();

    assert_eq!(object, second);
    println!(
        "pid={} open_us={} first_read_us={} warm_read_us={} payload_bytes={} handles_before={baseline:?} handles_open={retained:?} handles_clone={cloned:?}",
        std::process::id(),
        opened.as_micros(),
        read.as_micros(),
        reread.as_micros(),
        object.data().len()
    );

    drop(second);
    drop(object);
    drop(objects);
    drop(clone);

    println!("handles_after_drop={:?}", handles());
    assert_eq!(handles(), baseline);

    // Optional sampling interval is outside measured operations and retains no reader.
    if args.mode == Some(Mode::Hold) {
        std::thread::sleep(Duration::from_secs(1));
    }
    Ok(())
}

impl Objects

pub fn write_patch( &self, out: impl Write, entries: &[Entry], ) -> Result<(), Error>

Writes entries as a unified patch with default options and limits, without attributes or cancellation.

Wraps Self::write_patch_with with Options::default, no DiffAttributes and Limits::default. See the module documentation for the output format and its differences from git diff; Repo::write_patch applies the repository’s attributes.

Errors

Returns Error for write, storage, limit and abbreviation failures.

pub fn write_patch_with( &self, out: impl Write, entries: &[Entry], options: Options, attributes: Option<&mut DiffAttributes>, limits: Limits, cancel: &AtomicBool, ) -> Result<(), Error>

Writes entries as a unified patch under explicit options, attributes, limits and cancellation.

Entries are rendered in slice order; Comparison::entries already uses Git’s order. A change between a regular file or symlink and a different type (Git’s T status) is written as a deletion followed by an addition, as Git does. Gitlinks render as one Subproject commit <id> line per side, as git diff does without --submodule. A rename or copy prints its similarity from the entry. Identical identities print headers only.

With attributes, each side’s driver comes from its own path (the old path for the old side of a rename); see DiffAttributes. Gitlink sides have no driver. Attribute files are read as paths first need them.

Blob reads are synchronous. Cancellation is checked before each entry and inside each read and comparison; a single storage read or writer call cannot be interrupted.

Errors

Returns Error on the first write, storage, attribute, driver, limit, abbreviation or cancellation failure, after writing the complete patches of earlier entries and possibly part of the failing entry. Attribute and driver failures occur before the entry’s first line. Nothing is written to storage.

Examples found in repository

examples/patch.rs (lines 121-130)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let args = Args::parse();
    let temp = tempfile::tempdir()?;
    let mut out = io::BufWriter::new(io::stdout().lock());

    let Some(path) = args.path else {
        // The fixture compares two trees directly; no commits are needed.
        let repo = Repository::init(ObjectFormat::Sha1, temp.path().join("r"), InitKind::Bare)?;
        let loose = repo.loose_objects();
        let mut editor = TreeEditor::new(&loose);
        editor.set(b"notes.txt", loose.write_blob(b"one\ntwo\nthree\n")?)?;
        editor.set(b"old name", loose.write_blob(b"moved\ncontent\n")?)?;
        let old = editor.write()?;

        editor.set(b"notes.txt", loose.write_blob(b"one\n2\nthree")?)?;
        editor.remove(b"old name")?;
        editor.set(b"new name", loose.write_blob(b"moved\ncontent\n")?)?;
        let new = editor.write()?;

        let git = Repo::new(repo);
        git.write_patch(&mut out, old, new)?;
        out.flush()?;
        return Ok(());
    };

    if args.unified == 3 && !args.trusted && !args.no_indent_heuristic {
        Repo::discover(path)?.write_patch(&mut out, &args.old, &args.new)?;
        out.flush()?;
        return Ok(());
    }

    // Explicit options and limits go through the core API the handle composes.
    let environment = Environment::from_process();
    let repo = Repository::discover_with_config(path, &ConfigInputs::git_default(&environment)?)?;

    let (packs, rewrite_limits, limits) = if args.trusted {
        let diff = DiffLimits::default()
            .with_max_input_bytes(usize::MAX)
            .with_max_lines(usize::MAX)
            .with_max_trace(usize::MAX)
            .with_max_work(usize::MAX);

        // Keep the default rename candidate limit, which matches Git's, but lift resources.
        let rewrites = rewrites::Limits::default()
            .with_read(ReadLimits::trusted())
            .with_max_blob_bytes(usize::MAX)
            .with_max_spans(usize::MAX)
            .with_max_work(usize::MAX);

        (
            PackLimits::trusted(),
            rewrites,
            Limits::default()
                .with_read(ReadLimits::trusted())
                .with_diff(diff),
        )
    } else {
        (
            PackLimits::default(),
            rewrites::Limits::default(),
            Limits::default(),
        )
    };

    let objects = repo.objects_with(packs)?;
    let resolver = Resolver::new(&repo, &objects)?;
    let old = resolver.resolve_to(&args.old.parse()?, ObjectKind::Tree)?;
    let new = resolver.resolve_to(&args.new.parse()?, ObjectKind::Tree)?;

    let cancel = AtomicBool::new(false);
    let comparison = objects.diff_trees_with(
        Some(old),
        Some(new),
        rewrites::Options::default().with_track_empty(true),
        rewrite_limits,
        &cancel,
    )?;

    // Apply `.gitattributes` and `diff.<driver>` settings as `git diff` does.
    let mut attributes = repo.diff_attributes(&environment)?;
    objects.write_patch_with(
        &mut out,
        &comparison.entries,
        Options::default()
            .with_context_lines(args.unified)
            .with_indent_heuristic(!args.no_indent_heuristic),
        Some(&mut attributes),
        limits,
        &cancel,
    )?;

    out.flush()?;
    Ok(())
}

impl Objects

pub fn peel( &self, id: ObjectId, limits: PeelLimits, cancel: &AtomicBool, ) -> Result<PeeledObject, PeelError>

Resolves tags to a terminal object, checking each declared target kind.

Reads verified storage objects and decodes tag targets in the store’s format. Terminal commits must have decodable graph records; terminal trees remain uninterpreted, matching Git peeling. Metadata and canonical construction rules are separate. Cancellation is checked before and after each synchronous read, not during it. Memory is bounded by tag count and one per-read payload; total payload and per-read delta work are bounded separately. No files or references are changed and no partial result is returned.

Errors

Returns contextual PeelError for missing/corrupt/wrong-kind targets, malformed tags, cycles, limits or cancellation. Existing corrupt objects never become an absent result.

use std::sync::atomic::AtomicBool;

use girt::{
    InitKind, ObjectFormat, ObjectKind, PackLimits, PeelLimits, Repository, Tag, TagFields,
};

let directory = tempfile::tempdir()?;
let repo = Repository::init(
    ObjectFormat::Sha1,
    directory.path().join("r.git"),
    InitKind::Bare,
)?;

let loose = repo.loose_objects();
let blob = loose.write_blob(b"manifest")?;
let tag = Tag::new(TagFields {
    target: blob,
    target_kind: ObjectKind::Blob,
    name: b"v1".to_vec(),
    tagger: None,
    extra_headers: vec![],
    message: b"Reviewed".to_vec(),
})?;
let inner = loose.write_tag(&tag)?;

let outer = Tag::new(TagFields {
    target: inner,
    target_kind: ObjectKind::Tag,
    name: b"release".to_vec(),
    tagger: None,
    extra_headers: vec![],
    message: b"Release pointer".to_vec(),
})?;
let tip = loose.write_tag(&outer)?;

let objects = repo.objects_with(PackLimits::default())?;
let peeled = objects.peel(tip, PeelLimits::default(), &AtomicBool::new(false))?;

assert_eq!(peeled.tags, [tip, inner]);
assert_eq!(peeled.target, blob);
assert_eq!(peeled.kind, ObjectKind::Blob);

impl Objects

pub fn autosquash( &self, commits: &[ObjectId], max_commits: usize, ) -> Result<Todo, AutosquashError>

Creates a linear todo with Git’s fixup!, squash! and amend! subjects reordered.

Targets must precede the marked input in the supplied sequence. Exact subject or identity prefix matches take precedence over subject-prefix matches. Unmatched markers remain picks. Fixups attach after the target’s existing fixup group in input order; amend! selects fixup message replacement. The caller executes the returned plan separately.

Errors

Returns AutosquashError for the explicit count bound or unreadable inputs.

impl Objects

pub fn rebase( &self, commits: &[ObjectId], onto: ObjectId, committer: Signature, options: RebaseOptions, cancel: &AtomicBool, ) -> Result<Rebase, RebaseError>

Replays explicit ordered commits onto a destination entirely in memory.

The caller selects and orders the range; no ancestry walk, patch-ID filtering, fast-forward reuse or merge-topology reconstruction occurs. Each input creates a new single-parent commit or follows its explicit empty policy. Source authors are retained and the supplied committer is used for every new commit. Merge inputs require the replay mainline option.

Generated trees and blobs remain visible to subsequent steps through an in-memory overlay. The first conflict or stop-on-empty outcome returns completed progress and the unresolved replay. Skipped inputs map to the current tip. Errors or cancellation discard all progress; no object, state file, working file, index or reference has changed.

Errors

Returns RebaseError for input bounds, cancellation, unreadable inputs or replay failure.

pub fn rebase_with_driver( &self, commits: &[ObjectId], onto: ObjectId, committer: Signature, options: RebaseOptions, cancel: &AtomicBool, driver: &mut dyn TreeDriver, ) -> Result<Rebase, RebaseError>

Replays a sequence with the same caller-owned content driver at every step.

Uses Self::rebase’s explicit range, metadata, progress and publication contracts. Driver snapshots and side effects remain caller-owned; no attributes or processes run implicitly.

Errors

Returns RebaseError, retaining path-driver failures in the replay error source chain.

impl Objects

pub fn execute_todo( &self, todo: &Todo, onto: ObjectId, committer: Signature, options: Options, cancel: &AtomicBool, hooks: &mut dyn TodoHooks, ) -> Result<TodoRun, TodoExecutionError>

Executes a linear todo plan in memory, with explicit caller message and command hooks.

Supports noop/pick/reword/edit/squash/fixup/drop/exec/break/label/update-ref. Merge and reset commands are refused before any hook runs because this engine cannot resolve generated ancestry for recursive merge bases. Labels are checked for duplicates; topology execution remains unsupported. Fixup and squash replace the preceding commit’s tree/message while preserving its author and parents. Drop records no rewrite mapping.

No object, index, working file, state file or reference is installed by the executor. Hooks are explicitly caller-owned and may have side effects. For a stop, callers retain this result; resuming a complex edited plan requires a caller-owned continuation context.

Errors

Returns TodoExecutionError for unsupported merges, unknown labels, missing predecessors, invalid objects, replay/metadata failures, cancellation or a caller hook failure.

impl Objects

pub fn cherry_pick( &self, source: ObjectId, destination: ObjectId, committer: Signature, options: Options, cancel: &AtomicBool, ) -> Result<Replay, Error>

Computes a cherry-pick using source author and explicit new committer metadata.

Source signatures and opaque headers are not copied. Message bytes are retained, with an optional provenance paragraph. Root sources use an empty base. Merge sources require a one-based mainline. Conflicts never propose a commit; empty policy is applied only after a clean merge. No objects, refs, index or working files are written.

Errors

Returns Error for invalid mainline, unreadable inputs, invalid metadata or merge failure.

pub fn revert( &self, source: ObjectId, destination: ObjectId, committer: Signature, options: Options, cancel: &AtomicBool, ) -> Result<Replay, Error>

Computes the inverse of a commit, using the supplied identity as author and committer.

Uses Self::cherry_pick’s computation and publication contract. The message uses Git’s Revert "subject" title (Reapply when reverting a revert) and full source identity. For merge sources the explanation also names the selected parent. The original commit is the merge base; its parent supplies the inverse side. Root reverts select an empty inverse side.

Errors

Returns Error for invalid mainline, unreadable inputs, invalid metadata or merge failure.

pub fn cherry_pick_with_driver( &self, source: ObjectId, destination: ObjectId, committer: Signature, options: Options, cancel: &AtomicBool, driver: &mut dyn TreeDriver, ) -> Result<Replay, Error>

Computes cherry-pick with caller-owned per-path attribute/content policy.

Uses Self::cherry_pick’s metadata, bounds and publication contract. No attribute snapshot or external process is selected implicitly; driver side effects remain caller-owned.

Errors

Returns Error, preserving content-driver failures through the merge error source.

pub fn revert_with_driver( &self, source: ObjectId, destination: ObjectId, committer: Signature, options: Options, cancel: &AtomicBool, driver: &mut dyn TreeDriver, ) -> Result<Replay, Error>

Computes revert with caller-owned per-path attribute/content policy.

Uses Self::revert’s metadata, bounds and publication contract. Driver inputs use the reversed base/side roles; callback side effects remain caller-owned.

Errors

Returns Error, retaining original path-driver failures as merge error sources.

impl Objects

pub fn detect_rewrites( &self, old: Option<ObjectId>, new: Option<ObjectId>, options: Options, limits: Limits, targets: Option<&[&[u8]]>, cancel: &AtomicBool, ) -> Result<Vec<Rewrite>, Error>

Infers renames and optional copies between two stored trees, without changing storage.

Only additions of regular/executable blobs are destinations. Deleted blobs are rename sources; Copies::Modified additionally uses preimages of modified blobs, including mode-only changes, and permits source reuse. Copies::ModifiedPostimage scores their postimages but reports their preimage IDs. Symlinks, gitlinks and directories are never results. File/directory replacements use the structural comparison’s leaf changes. Both object formats are supported; candidate blobs are read and verified even for exact IDs.

Exact identity matches precede unique-basename pairing and exhaustive edited inference. Unique unmatched basenames pair without copies at halfway from the minimum score to 100%. This can prefer a basename pair over a more similar differently named destination. Exact ties prefer an unused deleted source, then equal basename, then source raw path order. Edited ties prefer higher rounded percentage, equal basename, source path, then destination path; selected pairs greedily consume destinations and (without copies) sources. This explicit deterministic policy does not promise Git’s every heuristic pairing choice. Rewrite defines scoring.

targets is an optional set of exact destination byte paths, applied after all inference and classification. It cannot change a tie or convert a copy into a rename. Results sort by target bytes. None allows all; an empty slice returns no records but still performs validation/inference. Paths need no OS/UTF-8 conversion.

Cancellation is checked before validation, between reads/candidates, during span scanning, and before and after sorting. Individual storage reads, allocation, tree parsing and sorting cannot be interrupted. Callers own worker scheduling and must leave cancel set until return. No attributes, clean/smudge/textconv drivers, index or worktree are consulted: these are comparisons of stored blob bytes. Callers own configuration and merge/history policy.

Self::detect_rewrites_or_exact instead returns the pairs already found when the Options::candidate_limit skips exhaustive edited-content detection.

Errors

Returns Error on invalid options, tree/blob storage failures, missing/wrong-kind blobs, cancellation, or exhausted candidate/resource limits. Errors return no partial inference; no repository state is changed. Exact matching is attempted before the candidate limit, but storage and work bounds apply throughout. See Limits for memory accounting.

use std::sync::atomic::AtomicBool;

use girt::rewrites::{Kind, Limits, Options};
use girt::{EntryMode, InitKind, ObjectFormat, Repository, Tree, TreeEntry};

let directory = tempfile::tempdir()?;
let repo = Repository::init(
    ObjectFormat::Sha1,
    directory.path().join("r"),
    InitKind::Bare,
)?;

let loose = repo.loose_objects();
let tree = |files: &[(&[u8], &[u8])]| -> Result<_, Box<dyn std::error::Error>> {
    let entries = files
        .iter()
        .map(|(name, bytes)| {
            Ok(TreeEntry {
                name: name.to_vec(),
                mode: EntryMode::Blob,
                id: loose.write_blob(bytes)?,
            })
        })
        .collect::<Result<Vec<_>, Box<dyn std::error::Error>>>()?;
    Ok(loose.write_tree(&Tree::new(ObjectFormat::Sha1, entries)?)?)
};

let old = tree(&[(b"before", b"same content\n")])?;
let new = tree(&[(b"after", b"same content\n")])?;

let records = repo.objects_with(Default::default())?.detect_rewrites(
    Some(old),
    Some(new),
    Options::default(),
    Limits::default(),
    None,
    &AtomicBool::new(false),
)?;

assert_eq!(records[0].kind, Kind::Rename);
assert_eq!(records[0].similarity, 100);
assert_eq!(records[0].source_id, records[0].target_id);

Examples found in repository

examples/rewrites.rs (lines 29-36)

fn main() -> girt::Result<()> {
    let args = Args::parse();
    let repo = Repository::open(args.repository)?;
    let objects = repo.objects()?;

    let records = objects.detect_rewrites(
        Some(args.old_tree),
        Some(args.new_tree),
        Options::default(),
        Limits::default(),
        None,
        &AtomicBool::new(false),
    )?;

    let mut output = io::stdout().lock();
    for record in records {
        write!(output, "{}{:03}\0", record.kind.letter(), record.similarity)?;
        output.write_all(&record.source)?;
        output.write_all(&[0])?;
        output.write_all(&record.target)?;
        output.write_all(&[0])?;
    }
    Ok(())
}

pub fn detect_rewrites_or_exact( &self, old: Option<ObjectId>, new: Option<ObjectId>, options: Options, limits: Limits, targets: Option<&[&[u8]]>, cancel: &AtomicBool, ) -> Result<Detection, Error>

Infers rewrites as Self::detect_rewrites does, keeping pre-limit matches.

When the remaining candidates exceed Options::candidate_limit, edited-content detection is skipped and Detection::inexact_skipped says so. Exact and unique-basename pairs are still returned. Callers decide whether to warn, retry with a higher limit, or accept the pairs found before the limit.

Errors

Returns Error on the same conditions as Self::detect_rewrites, except that an exceeded candidate limit is reported in the result rather than as Error::Candidates.

Keep exact renames when edited detection is too expensive

The fallback API, available since 0.10.0, keeps a useful result for large changes while making its limitation visible. Unpaired additions/deletions must remain visible to the caller. Other work limits and storage failures still return errors, never partial detection.

use std::sync::atomic::AtomicBool;

use girt::rewrites::{Error, Limits, Options};
use girt::{EntryMode, InitKind, ObjectFormat, Repository, Tree, TreeEntry};

let directory = tempfile::tempdir()?;
let repo = Repository::init(
    ObjectFormat::Sha1,
    directory.path().join("r"),
    InitKind::Bare,
)?;

let loose = repo.loose_objects();
let tree = |files: &[(&[u8], &[u8])]| -> Result<_, Box<dyn std::error::Error>> {
    let entries = files
        .iter()
        .map(|(name, bytes)| {
            Ok(TreeEntry {
                name: name.to_vec(),
                mode: EntryMode::Blob,
                id: loose.write_blob(bytes)?,
            })
        })
        .collect::<Result<Vec<_>, Box<dyn std::error::Error>>>()?;
    Ok(loose.write_tree(&Tree::new(ObjectFormat::Sha1, entries)?)?)
};

let old = tree(&[
    (b"exact-old", b"identical\n"),
    (b"edited-old", b"line one\nline two\n"),
])?;
let new = tree(&[
    (b"exact-new", b"identical\n"),
    (b"edited-new", b"line one\nline THREE\n"),
])?;

let objects = repo.objects_with(Default::default())?;
let options = Options::default().with_candidate_limit(0);
let cancel = AtomicBool::new(false);
let detection = objects.detect_rewrites_or_exact(
    Some(old),
    Some(new),
    options,
    Limits::default(),
    None,
    &cancel,
)?;

assert_eq!(detection.rewrites.len(), 1); // The identical pair survived.
assert_eq!(detection.rewrites[0].source, b"exact-old");
let skipped = detection.inexact_skipped.expect("one edited pair remains");
assert_eq!((skipped.sources, skipped.targets, skipped.limit), (1, 1, 0));
assert_eq!(skipped.suggested_limit(), 1);

assert!(matches!(
    objects.detect_rewrites(
        Some(old),
        Some(new),
        options,
        Limits::default(),
        None,
        &cancel
    ),
    Err(Error::Candidates { .. })
));

impl Objects

pub fn apply_stash( &self, saved: &Snapshot, input: ApplyInput, options: ApplyOptions, cancel: &AtomicBool, ) -> Result<Apply, Error>

Reapplies saved changes onto an explicit current index, without writing repository state.

Uses the stash base as the common ancestor and the saved worktree as theirs. Optional index restoration merges the saved index delta first; a conflict there returns immediately with original sides. Ordinary clean apply keeps current staged changes and stages paths newly added by the stash, matching Git. A tracked conflict retains merge stages instead.

Saved untracked paths are checked against current tracked and caller-observed occupied paths, including ancestor/descendant collisions. Even identical existing files are refused. Guarded checkout must protect tracked worktree edits and revalidate the occupied observation. This does not run filters, discover untracked paths, install objects or drop a stash entry.

Errors

Returns input/merge/preparation failures, bounds or Error::UntrackedCollision. Existing merge limits and unsupported structural layouts remain explicit refusals.

impl Objects

pub fn create_stash( &self, input: SaveInput, author: Signature, committer: Signature, options: SaveOptions, cancel: &AtomicBool, ) -> Result<Option<Save>, Error>

Constructs saved commits and cleanup, returning None when no selected changes exist.

Both identities are explicit, matching Git’s separate author/committer environment. Default index/untracked messages end in LF; the worktree message has no added final LF. No trees, commits, refs, index or files are written. Staged cleanup uses the existing merge engine; it can retain conflicts where Git’s patch-based cleanup refuses an overlapping worktree edit. Its conflict result never authorizes cleanup publication.

Errors

Returns invalid input metadata, unsupported selection or object/merge errors. Tree roots are read, but this does not prove recursive object connectivity.

impl Objects

pub fn compare_trees_with( &self, old: Option<ObjectId>, new: Option<ObjectId>, limits: TreeCompareLimits, cancel: &AtomicBool, ) -> Result<Vec<TreeChange>, TreeCompareError>

Compares two tree IDs recursively, using None for an empty side.

Returns leaf additions, removals and changes in ascending lexicographic raw full-path byte order (shorter prefix first). Git tree ordering is validated before pairing entries by byte name: files and directories with the same name must pair even when their positions in Git order differ. A file/directory replacement yields a removal/addition at the file path and additions/removals below the directory. Empty directories yield no leaf records. No rename/copy detection, text diff, index or worktree access occurs; use Self::compare_trees_matching to limit paths.

Equal subtree IDs, including equal roots, are trusted and skipped without any read. This establishes structural identity, not validity or existence. Other encountered trees are identity-verified by storage, parsed and structurally validated. Blob, symlink and gitlink targets are never read, even when changed; dangling or wrong-kind leaf targets therefore remain unvalidated. Gitlinks are not interpreted as local subtrees.

I/O and comparison are synchronous and read-only. Traversal uses an explicit stack, not recursion. Set cancel from another thread and leave it set until return. Checks occur before starting (even for equal roots), between tree reads and entry processing, and before and after sorting output. Individual reads, parsing, validation and sorting cannot be interrupted; cancellation is cooperative, without a wall-clock guarantee. Callers using an async runtime should run the whole operation on a caller-bounded blocking worker.

Errors

Returns TreeCompareError for a visited missing, wrong-kind, corrupt, malformed or structurally invalid tree, cancellation, or an exhausted bound. Read/parse failures include the tree ID and byte path (empty for the root). No partial results or filesystem mutations are produced. Both object formats and the five modes accepted by Tree::parse are supported.

use std::sync::atomic::AtomicBool;

use girt::{
    EntryMode, InitKind, ObjectFormat, PackLimits, Repository, Tree, TreeCompareLimits,
    TreeEntry,
};

let directory = tempfile::tempdir()?;
let repo = Repository::init(
    ObjectFormat::Sha1,
    directory.path().join("r"),
    InitKind::Bare,
)?;

let loose = repo.loose_objects();
let tree = |content: &[u8]| -> Result<_, Box<dyn std::error::Error>> {
    let id = loose.write_blob(content)?;
    let entry = TreeEntry {
        mode: EntryMode::Blob,
        name: b"notes.txt".to_vec(),
        id,
    };
    Ok(loose.write_tree(&Tree::new(ObjectFormat::Sha1, vec![entry])?)?)
};
let (old, new) = (tree(b"draft\n")?, tree(b"final\n")?);

let objects = repo.objects_with(PackLimits::default())?;
let cancel = AtomicBool::new(false);
let limits = TreeCompareLimits::default();
let changes = objects.compare_trees_with(Some(old), Some(new), limits, &cancel)?;
assert_eq!(changes.len(), 1);
assert_eq!(changes[0].path, b"notes.txt");
assert_ne!(
    changes[0].old.map(|old| old.id),
    changes[0].new.map(|new| new.id)
);

// `None` stands for an empty tree on either side.
assert!(
    objects
        .compare_trees_with(None, None, limits, &cancel)?
        .is_empty()
);

pub fn compare_trees_matching( &self, old: Option<ObjectId>, new: Option<ObjectId>, paths: &Pathspec, limits: TreeCompareLimits, cancel: &AtomicBool, ) -> Result<Vec<TreeChange>, TreeCompareError>

Self::compare_trees_with, keeping only changes at paths paths selects.

This is the comparison git diff-tree -r <old> <new> -- <pathspec> makes. Subtrees the pathspec cannot reach are not read, and paths below a subtree it selects whole are not tested, so a narrow pathspec over a large tree reads only the trees on the way to it.

use std::sync::atomic::AtomicBool;

use girt::pathspec::{Context, Pathspec};
use girt::tree::TreeEditor;
use girt::{InitKind, ObjectFormat, Repository};

let directory = tempfile::tempdir()?;
let repo = Repository::init(
    ObjectFormat::Sha1,
    directory.path().join("r"),
    InitKind::Bare,
)?;
let loose = repo.loose_objects();
let mut editor = TreeEditor::new(&loose);
editor.set(b"src/lib.rs", loose.write_blob(b"old\n")?)?;
editor.set(b"docs/guide.md", loose.write_blob(b"old\n")?)?;
let old = editor.write()?;
editor.set(b"src/lib.rs", loose.write_blob(b"new\n")?)?;
editor.set(b"docs/guide.md", loose.write_blob(b"new\n")?)?;
let new = editor.write()?;

let paths = Pathspec::parse(["*.rs"], &Context::new())?;
let objects = repo.objects()?;
let changes = objects.compare_trees_matching(
    Some(old),
    Some(new),
    &paths,
    Default::default(),
    &AtomicBool::new(false),
)?;
assert_eq!(changes.len(), 1);
assert_eq!(changes[0].path, b"src/lib.rs");

Errors

Returns the errors of Self::compare_trees_with, and TreeCompareError::Unsupported for a pathspec with attr: magic, which needs attributes a tree comparison does not load.

pub fn compare_trees( &self, old: Option<ObjectId>, new: Option<ObjectId>, ) -> Result<Vec<TreeChange>, TreeCompareError>

Compares two trees with TreeCompareLimits::default and no cancellation.

Equivalent to self.compare_trees_with(old, new, TreeCompareLimits::default(), &never) with a flag that is never set; see Self::compare_trees_with for ordering and verification.

Errors

Returns the errors of Self::compare_trees_with except cancellation.

Examples found in repository

examples/compare_trees.rs (line 77)

fn main() -> girt::Result<()> {
    let args = Args::parse();
    let temporary;
    let (repo, old, new) =
        if let (Some(path), Some(old), Some(new)) = (args.repo, args.old, args.new) {
            (Repository::open(path)?, old.0, new.0)
        } else {
            temporary = tempfile::tempdir()?;
            let repo = Repository::init(
                girt::ObjectFormat::Sha1,
                temporary.path().join("sample"),
                InitKind::Bare,
            )?;

            let store = repo.loose_objects();
            let old_blob = store.write_blob(b"hello\n")?;
            let new_blob = store.write_blob(b"hello, trees\n")?;

            let old = store.write_tree(&Tree::new(
                girt::ObjectFormat::Sha1,
                vec![TreeEntry {
                    name: b"hello.txt".to_vec(),
                    mode: EntryMode::Blob,
                    id: old_blob,
                }],
            )?)?;
            let new = store.write_tree(&Tree::new(
                girt::ObjectFormat::Sha1,
                vec![TreeEntry {
                    name: b"hello.txt".to_vec(),
                    mode: EntryMode::Executable,
                    id: new_blob,
                }],
            )?)?;

            (repo, Some(old), Some(new))
        };

    let objects = repo.objects()?;
    let changes = objects.compare_trees(old, new)?;

    for change in changes {
        // Git's quoting keeps non-UTF-8 names and control bytes distinguishable on a terminal.
        println!(
            "{} {}: {} -> {}",
            change.status().letter(),
            quote_path(&change.path),
            describe(change.old),
            describe(change.new)
        );
    }

    Ok(())
}

examples/content_diff.rs (line 41)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let root = tempfile::tempdir()?;
    let repo = Repository::init(
        girt::ObjectFormat::Sha1,
        root.path().join("repo"),
        InitKind::Bare,
    )?;

    let store = repo.loose_objects();
    let old_blob = store.write_blob(b"heading\r\nold\n")?;
    let new_blob = store.write_blob(b"heading\r\nnew\xff")?;

    let old = store.write_tree(&Tree::new(
        girt::ObjectFormat::Sha1,
        vec![TreeEntry {
            name: b"example.txt".to_vec(),
            mode: EntryMode::Blob,
            id: old_blob,
        }],
    )?)?;
    let new = store.write_tree(&Tree::new(
        girt::ObjectFormat::Sha1,
        vec![TreeEntry {
            name: b"example.txt".to_vec(),
            mode: EntryMode::Executable,
            id: new_blob,
        }],
    )?)?;

    let objects = repo.objects()?;
    let cancel = AtomicBool::new(false);
    let limits = DiffLimits::default();

    let changes = objects.compare_trees(Some(old), Some(new))?;
    for change in changes {
        println!(
            "{}: {:?} -> {:?}",
            escaped(&change.path),
            change.old.map(|v| v.mode),
            change.new.map(|v| v.mode)
        );

        // Gitlinks require a submodule policy; the blob adapter deliberately rejects them.
        let content = BlobContent::read(
            &objects,
            &change,
            ReadLimits::default(),
            limits.max_input_bytes,
            &cancel,
        )?;

        match diff(
            &content.old,
            &content.new,
            BinaryMode::Auto,
            limits,
            &cancel,
        )? {
            ContentDiff::Unchanged => println!("  unchanged content (check modes/existence above)"),
            ContentDiff::Binary { old, new } => {
                println!("  binary: {} -> {} bytes", old.len(), new.len())
            }
            ContentDiff::Text(text) => {
                for edit in text.edits() {
                    println!(
                        "  old lines {:?} -> new lines {:?} (zero-based)",
                        edit.old_lines, edit.new_lines
                    );
                    println!("  - {}", escaped(&text.old_bytes()[edit.old_bytes.clone()]));
                    println!("  + {}", escaped(&text.new_bytes()[edit.new_bytes.clone()]));
                }
            }
            _ => return Err("unsupported content diff kind".into()),
        }
    }

    Ok(())
}

impl Objects

pub fn diff_trees( &self, old: Option<ObjectId>, new: Option<ObjectId>, ) -> Result<Comparison, Error>

Compares trees and infers renames using default options and limits, without cancellation.

Wraps Self::diff_trees_with with default options and limits.

Errors

Returns storage, malformed-tree, resource or inference errors from the two explicit APIs.

pub fn diff_trees_with( &self, old: Option<ObjectId>, new: Option<ObjectId>, options: Options, limits: Limits, cancel: &AtomicBool, ) -> Result<Comparison, Error>

Compares trees and infers rewrites under explicit policy, limits and cancellation. Copies retain their source change; renames consume deleted sources and added targets. The existing rewrite limits supply tree bounds for one structural traversal, reused during inference. Candidate-limit skips retain exact matches and are reported on the result; resource-budget exhaustion still returns an error. Memory grows with admitted tree changes and candidate content; path lookups use ordered maps and sets.

Errors

Returns storage, malformed-tree, resource, cancellation or inference errors. Nothing is written.

Examples found in repository

examples/patch.rs (lines 111-117)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let args = Args::parse();
    let temp = tempfile::tempdir()?;
    let mut out = io::BufWriter::new(io::stdout().lock());

    let Some(path) = args.path else {
        // The fixture compares two trees directly; no commits are needed.
        let repo = Repository::init(ObjectFormat::Sha1, temp.path().join("r"), InitKind::Bare)?;
        let loose = repo.loose_objects();
        let mut editor = TreeEditor::new(&loose);
        editor.set(b"notes.txt", loose.write_blob(b"one\ntwo\nthree\n")?)?;
        editor.set(b"old name", loose.write_blob(b"moved\ncontent\n")?)?;
        let old = editor.write()?;

        editor.set(b"notes.txt", loose.write_blob(b"one\n2\nthree")?)?;
        editor.remove(b"old name")?;
        editor.set(b"new name", loose.write_blob(b"moved\ncontent\n")?)?;
        let new = editor.write()?;

        let git = Repo::new(repo);
        git.write_patch(&mut out, old, new)?;
        out.flush()?;
        return Ok(());
    };

    if args.unified == 3 && !args.trusted && !args.no_indent_heuristic {
        Repo::discover(path)?.write_patch(&mut out, &args.old, &args.new)?;
        out.flush()?;
        return Ok(());
    }

    // Explicit options and limits go through the core API the handle composes.
    let environment = Environment::from_process();
    let repo = Repository::discover_with_config(path, &ConfigInputs::git_default(&environment)?)?;

    let (packs, rewrite_limits, limits) = if args.trusted {
        let diff = DiffLimits::default()
            .with_max_input_bytes(usize::MAX)
            .with_max_lines(usize::MAX)
            .with_max_trace(usize::MAX)
            .with_max_work(usize::MAX);

        // Keep the default rename candidate limit, which matches Git's, but lift resources.
        let rewrites = rewrites::Limits::default()
            .with_read(ReadLimits::trusted())
            .with_max_blob_bytes(usize::MAX)
            .with_max_spans(usize::MAX)
            .with_max_work(usize::MAX);

        (
            PackLimits::trusted(),
            rewrites,
            Limits::default()
                .with_read(ReadLimits::trusted())
                .with_diff(diff),
        )
    } else {
        (
            PackLimits::default(),
            rewrites::Limits::default(),
            Limits::default(),
        )
    };

    let objects = repo.objects_with(packs)?;
    let resolver = Resolver::new(&repo, &objects)?;
    let old = resolver.resolve_to(&args.old.parse()?, ObjectKind::Tree)?;
    let new = resolver.resolve_to(&args.new.parse()?, ObjectKind::Tree)?;

    let cancel = AtomicBool::new(false);
    let comparison = objects.diff_trees_with(
        Some(old),
        Some(new),
        rewrites::Options::default().with_track_empty(true),
        rewrite_limits,
        &cancel,
    )?;

    // Apply `.gitattributes` and `diff.<driver>` settings as `git diff` does.
    let mut attributes = repo.diff_attributes(&environment)?;
    objects.write_patch_with(
        &mut out,
        &comparison.entries,
        Options::default()
            .with_context_lines(args.unified)
            .with_indent_heuristic(!args.no_indent_heuristic),
        Some(&mut attributes),
        limits,
        &cancel,
    )?;

    out.flush()?;
    Ok(())
}

pub fn diff_trees_matching( &self, old: Option<ObjectId>, new: Option<ObjectId>, paths: &Pathspec, options: Options, limits: Limits, cancel: &AtomicBool, ) -> Result<Comparison, Error>

Self::diff_trees_with, limited to paths paths selects.

As in git diff -M <old> <new> -- <pathspec>, the pathspec applies before inference: a file moved from outside the pathspec to inside it is an addition, not a rename.

Errors

Returns the errors of Self::diff_trees_with, and an unsupported-pathspec tree comparison error for attr: magic.

Trait Implementations

impl Clone for Objects

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Objects

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.