Struct Object 

pub struct Object { /* private fields */ }

An owned, identity-verified object kind and exact uncompressed payload.

Storage framing is validated; tree, commit, and tag payload syntax is not. Pass Self::data to crate::Tree::parse, crate::Commit::parse, or crate::Tag::parse as appropriate.

A packed payload may be shared with the reader’s delta base cache, and clones share it too, so borrowing it through Self::data costs no copy. Self::into_data copies it only while another Object or the cache shares it.

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 object = objects
    .read_with(id, ReadLimits::default())?
    .ok_or("missing blob")?;

assert_eq!(object.data(), b"payload\n");
assert_eq!(object.id(), id);

Implementations

impl Object

pub fn object_format(&self) -> ObjectFormat

The storage format in which the identity was verified.

pub fn kind(&self) -> ObjectKind

The verified Git object type.

Examples found in repository

examples/packed_repository.rs (line 29)

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/write_pack.rs (line 50)

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(())
}

pub fn data(&self) -> &[u8]

Exact uncompressed payload, without the Git object header.

Examples found in repository

examples/packed_repository.rs (line 31)

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 93)

    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 51)

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/fetch_local.rs (line 83)

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 85)

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(())
}

examples/storage_resources.rs (line 146)

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 into_data(self) -> Vec<u8>

Takes ownership of the payload, copying it if another Object or the cache shares it.

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 object = objects
    .read_with(id, ReadLimits::default())?
    .ok_or("blob absent")?;

let retained = object.clone();
let owned = object.into_data(); // A shared payload may be copied; the other owner stays usable.
assert_eq!(owned, retained.data());

pub fn id(&self) -> ObjectId

Hashes the kind, canonical header, and payload.

Examples found in repository

examples/packed_repository.rs (line 30)

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(())
}

Trait Implementations

impl Clone for Object

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 Object

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

Formats the value using the given formatter.

impl Eq for Object

impl PartialEq for Object

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for Object