pub struct Objects<'repo> { /* private fields */ }Expand description
Read and write Git objects through a Repository handle.
Implementations§
Source§impl<'repo> Objects<'repo>
impl<'repo> Objects<'repo>
Sourcepub fn new(repo: &'repo Repository) -> Self
pub fn new(repo: &'repo Repository) -> Self
Bind object operations to repo.
Sourcepub fn repository(&self) -> &'repo Repository
pub fn repository(&self) -> &'repo Repository
Underlying repository.
Sourcepub fn contains(&self, oid: &ObjectId) -> Result<bool>
pub fn contains(&self, oid: &ObjectId) -> Result<bool>
Returns whether oid is present in this repository’s object database.
§Errors
Propagates a backend failure when no object source has oid (see
crate::odb::Odb::contains) instead of reporting it as missing.
§Examples
use grit_lib::objects::ObjectKind;
use grit_lib::repo::{InitOptions, Repository};
let dir = std::env::temp_dir().join("grit-objects-handle-doc");
let repo = Repository::init(&dir, &InitOptions::default())?;
let oid = repo.objects().write(ObjectKind::Blob, b"hello")?;
assert!(repo.objects().contains(&oid)?);Sourcepub fn read(&self, oid: &ObjectId) -> Result<Object>
pub fn read(&self, oid: &ObjectId) -> Result<Object>
Read the object named oid.
§Errors
Returns crate::error::Error::ObjectNotFound when the object is missing.
§Examples
use grit_lib::objects::ObjectKind;
use grit_lib::repo::{InitOptions, Repository};
let dir = std::env::temp_dir().join("grit-objects-read-doc");
let repo = Repository::init(&dir, &InitOptions::default())?;
let oid = repo.objects().write(ObjectKind::Blob, b"payload")?;
let obj = repo.objects().read(&oid)?;
assert_eq!(obj.data, b"payload");Sourcepub fn read_info(&self, oid: &ObjectId) -> Result<ObjectInfo>
pub fn read_info(&self, oid: &ObjectId) -> Result<ObjectInfo>
Read object type and size without inflating full blob bodies when possible.
§Errors
Propagates object lookup failures from the ODB.
Sourcepub fn read_commit(&self, oid: &ObjectId) -> Result<CommitData>
pub fn read_commit(&self, oid: &ObjectId) -> Result<CommitData>
Read oid and parse it as a commit (annotated tags are not followed).
§Errors
See crate::objects::odb::Odb::read_commit: a missing object, an object that is not
a commit (crate::error::Error::UnexpectedObjectKind), or a malformed commit.
§Examples
use grit_lib::objects::ObjectKind;
use grit_lib::repo::{InitOptions, Repository};
let dir = std::env::temp_dir().join("grit-objects-read-commit-doc");
let repo = Repository::init(&dir, &InitOptions::default())?;
let tree = repo.objects().write(ObjectKind::Tree, b"")?;
let body = format!(
"tree {tree}\nauthor A <a@example.com> 0 +0000\ncommitter A <a@example.com> 0 +0000\n\nfirst\n"
);
let commit = repo.objects().write(ObjectKind::Commit, body.as_bytes())?;
assert_eq!(repo.objects().read_commit(&commit)?.message, "first\n");
assert_eq!(repo.objects().commit_tree(&commit)?, tree);
assert!(repo.objects().read_commit(&tree).is_err());Sourcepub fn commit_tree(&self, oid: &ObjectId) -> Result<ObjectId>
pub fn commit_tree(&self, oid: &ObjectId) -> Result<ObjectId>
The root tree of the commit oid, decoding only the commit headers.
§Errors
Same as Self::read_commit.
Sourcepub fn hash(&self, kind: ObjectKind, data: &[u8]) -> Result<ObjectId>
pub fn hash(&self, kind: ObjectKind, data: &[u8]) -> Result<ObjectId>
Hash data as a Git object of kind without writing to disk.
§Errors
Returns crate::error::Error::HashCollision when sha1dc detects a chosen-prefix collision.
Sourcepub fn write(&self, kind: ObjectKind, data: &[u8]) -> Result<ObjectId>
pub fn write(&self, kind: ObjectKind, data: &[u8]) -> Result<ObjectId>
Validate and store an object, returning its id.
Tree, commit and tag payloads must pass the same checks as git hash-object -t <kind>
(without --literally): sorted, duplicate-free tree entries with allowed modes and
names, and well-formed tree/parent/author/committer/tagger headers. Blobs
are stored as given. To build trees and commits from typed values instead of raw
bytes, use Self::write_tree and Self::write_commit.
§Errors
crate::error::Error::InvalidObjectwhen the payload would failgit fsck; nothing is written.crate::error::Error::HashCollisionand zlib or filesystem errors from the ODB.
§Examples
See also the guide_objects example program.
Sourcepub fn write_literally(&self, kind: ObjectKind, data: &[u8]) -> Result<ObjectId>
pub fn write_literally(&self, kind: ObjectKind, data: &[u8]) -> Result<ObjectId>
Store data as an object of kind without validating its structure.
The equivalent of git hash-object --literally: use it only to reproduce or test
corrupt objects. Repositories containing such objects fail git fsck.
§Errors
crate::error::Error::HashCollision and zlib or filesystem errors from the ODB.
Sourcepub fn write_tree(
&self,
entries: impl IntoIterator<Item = TreeEntry>,
) -> Result<ObjectId>
pub fn write_tree( &self, entries: impl IntoIterator<Item = TreeEntry>, ) -> Result<ObjectId>
Write a tree object from entries, given in any order.
Entries are sorted into Git’s tree order. Entry objects are not required to exist
(as with git mktree --missing), so trees can be built bottom-up or point at
objects a partial clone has not fetched.
§Errors
crate::error::Error::InvalidTreeEntrywhen an entry has an empty,.,..,.git-alias or slash/NUL-containing name, a mode other than100644,100755,120000,40000or160000, the null object id, an object id of the wrong hash algorithm, a name over 4096 bytes, or a name used by another entry.crate::error::Error::HashCollisionand zlib or filesystem errors from the ODB.
§Examples
use grit_lib::objects::{ObjectKind, TreeEntry};
use grit_lib::repo::{InitOptions, Repository};
let dir = tempfile::tempdir()?;
let repo = Repository::init(dir.path(), &InitOptions::new().with_bare(true))?;
let blob = repo.objects().write(ObjectKind::Blob, b"hello\n")?;
let entry = |name: &str| TreeEntry { mode: 0o100644, name: name.into(), oid: blob };
let tree = repo.objects().write_tree([entry("b"), entry("a")])?;
let names: Vec<_> = grit_lib::objects::parse_tree(&repo.objects().read(&tree)?.data)?
.into_iter()
.map(|e| e.name)
.collect();
assert_eq!(names, [b"a".to_vec(), b"b".to_vec()]);Sourcepub fn write_commit(&self, commit: &NewCommit) -> Result<ObjectId>
pub fn write_commit(&self, commit: &NewCommit) -> Result<ObjectId>
Write the commit described by commit and return its id.
The tree must exist and be a tree, and every parent must exist and be a commit
(the checks git commit-tree makes). When grit.changeIds is enabled (the
default) and no id was set with NewCommit::with_change_id, the commit gets a
fresh change-id header. The commit is not signed and no ref is updated; use
crate::porcelain::commit::create_commit to commit the index onto a branch.
§Errors
crate::error::Error::InvalidSignaturewhen the author or committer has a<,>or control character in its name or email, a time before the Unix epoch, or a UTC offset with a seconds component.crate::error::Error::ObjectNotFoundwhen the tree or a parent is missing, andcrate::error::Error::UnexpectedObjectKindwhen one has the wrong kind.- Config loading errors from
Repository::config(read forgrit.changeIds). - The errors of
Self::write.
§Examples
See NewCommit.