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. Each entry’s object must exist in this
repository with the kind implied by its mode (tree or blob; gitlink 160000 entries
may reference a commit that is not stored), matching git mktree without --missing.
Use
Self::write_tree_with with WriteTreeOptions::allow_missing when building
trees bottom-up or referencing 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, a name used by another entry, or a symlink to a reserved metadata file name (.gitmodules,.gitattributes, and related spellings).crate::error::Error::ObjectNotFoundwhen a required entry object is missing.crate::error::Error::UnexpectedObjectKindwhen a stored object has the wrong kind.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_tree_with(
&self,
entries: impl IntoIterator<Item = TreeEntry>,
options: WriteTreeOptions,
) -> Result<ObjectId>
pub fn write_tree_with( &self, entries: impl IntoIterator<Item = TreeEntry>, options: WriteTreeOptions, ) -> Result<ObjectId>
Write a tree object from entries with options.
Same validation and sorting as Self::write_tree, except that missing blob and
tree oids are accepted when WriteTreeOptions::allow_missing is set.
§Errors
Same as Self::write_tree.
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.