gix_object/
lib.rs

1//! This crate provides types for [read-only git objects][crate::ObjectRef] backed by bytes provided in git's serialization format
2//! as well as [mutable versions][Object] of these. Both types of objects can be encoded.
3//!
4//! ## Decode Borrowed Objects
5//!
6//! ```
7//! let object = gix_object::ObjectRef::from_loose(b"blob 5\0hello", gix_hash::Kind::Sha1).unwrap();
8//! let blob = object.as_blob().unwrap();
9//!
10//! assert_eq!(blob.data, b"hello");
11//! assert_eq!(object.kind(), gix_object::Kind::Blob);
12//! ```
13//!
14//! ## Mutate And Encode Owned Objects
15//!
16//! ```
17//! use gix_object::WriteTo;
18//!
19//! let object = gix_object::ObjectRef::from_loose(b"blob 5\0hello", gix_hash::Kind::Sha1)
20//!     .unwrap()
21//!     .into_owned()
22//!     .unwrap();
23//! let mut blob = object.into_blob();
24//! blob.data.extend_from_slice(b" world");
25//!
26//! let mut out = Vec::new();
27//! blob.write_to(&mut out).unwrap();
28//! assert_eq!(out, b"hello world");
29//! assert_eq!(blob.loose_header().as_slice(), b"blob 11\0");
30//! ```
31//! ## Feature Flags
32#![cfg_attr(
33    all(doc, feature = "document-features"),
34    doc = ::document_features::document_features!()
35)]
36#![cfg_attr(all(doc, feature = "document-features"), feature(doc_cfg))]
37#![deny(missing_docs, rust_2018_idioms)]
38#![forbid(unsafe_code)]
39
40use std::borrow::Cow;
41
42/// For convenience to allow using `bstr` without adding it to own cargo manifest.
43pub use bstr;
44use bstr::{BStr, BString, ByteSlice};
45/// For convenience to allow using `gix-date` without adding it to own cargo manifest.
46pub use gix_date as date;
47use smallvec::SmallVec;
48
49///
50pub mod commit;
51mod object;
52///
53pub mod tag;
54///
55pub mod tree;
56
57mod blob;
58///
59pub mod data;
60
61///
62pub mod find;
63
64///
65pub mod write {
66    /// The error type returned by the [`Write`](crate::Write) trait.
67    pub type Error = Box<dyn std::error::Error + Send + Sync + 'static>;
68}
69
70mod traits;
71pub use traits::{Exists, Find, FindExt, FindObjectOrHeader, Header as FindHeader, HeaderExt, Write, WriteTo};
72
73pub mod encode;
74pub(crate) mod parse;
75
76///
77pub mod kind;
78
79/// The four types of objects that git differentiates.
80#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
81#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Copy)]
82#[allow(missing_docs)]
83pub enum Kind {
84    Tree,
85    Blob,
86    Commit,
87    Tag,
88}
89/// A chunk of any [`data`](BlobRef::data).
90#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Copy)]
91#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
92pub struct BlobRef<'a> {
93    /// The bytes themselves.
94    pub data: &'a [u8],
95}
96
97/// A mutable chunk of any [`data`](Blob::data).
98#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
99#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
100pub struct Blob {
101    /// The data itself.
102    pub data: Vec<u8>,
103}
104
105/// A git commit parsed using [`from_bytes()`](CommitRef::from_bytes()).
106///
107/// A commit encapsulates information about a point in time at which the state of the repository is recorded, usually after a
108/// change which is documented in the commit `message`.
109#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
110#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
111pub struct CommitRef<'a> {
112    /// HEX hash of tree object we point to.
113    ///
114    /// Use [`tree()`](CommitRef::tree()) to obtain a decoded version of it.
115    #[cfg_attr(feature = "serde", serde(borrow))]
116    pub tree: &'a BStr,
117    /// HEX hash of each parent commit. Empty for first commit in repository.
118    pub parents: SmallVec<[&'a BStr; 1]>,
119    /// The raw author header value as encountered during parsing.
120    ///
121    /// Use the [`author()`](CommitRef::author()) method to obtain a parsed version of it.
122    #[cfg_attr(feature = "serde", serde(borrow))]
123    pub author: &'a BStr,
124    /// The raw committer header value as encountered during parsing.
125    ///
126    /// Use the [`committer()`](CommitRef::committer()) method to obtain a parsed version of it.
127    #[cfg_attr(feature = "serde", serde(borrow))]
128    pub committer: &'a BStr,
129    /// The name of the message encoding, otherwise [UTF-8 should be assumed](https://github.com/git/git/blob/e67fbf927dfdf13d0b21dc6ea15dc3c7ef448ea0/commit.c#L1493:L1493).
130    pub encoding: Option<&'a BStr>,
131    /// The commit message documenting the change.
132    pub message: &'a BStr,
133    /// Extra header fields, in order of them being encountered, made accessible with the iterator returned by [`extra_headers()`](CommitRef::extra_headers()).
134    pub extra_headers: Vec<(&'a BStr, Cow<'a, BStr>)>,
135}
136
137/// Like [`CommitRef`], but as `Iterator` to support (up to) entirely allocation free parsing.
138/// It's particularly useful to traverse the commit graph without ever allocating arrays for parents.
139#[derive(Copy, Clone)]
140pub struct CommitRefIter<'a> {
141    data: &'a [u8],
142    state: commit::ref_iter::State,
143    hash_kind: gix_hash::Kind,
144}
145
146/// A mutable git commit, representing an annotated state of a working tree along with a reference to its historical commits.
147#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
148#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
149pub struct Commit {
150    /// The hash of recorded working tree state.
151    pub tree: gix_hash::ObjectId,
152    /// Hash of each parent commit. Empty for the first commit in repository.
153    pub parents: SmallVec<[gix_hash::ObjectId; 1]>,
154    /// Who wrote this commit.
155    pub author: gix_actor::Signature,
156    /// Who committed this commit.
157    ///
158    /// This may be different from the `author` in case the author couldn't write to the repository themselves and
159    /// is commonly encountered with contributed commits.
160    pub committer: gix_actor::Signature,
161    /// The name of the message encoding, otherwise [UTF-8 should be assumed](https://github.com/git/git/blob/e67fbf927dfdf13d0b21dc6ea15dc3c7ef448ea0/commit.c#L1493:L1493).
162    pub encoding: Option<BString>,
163    /// The commit message documenting the change.
164    pub message: BString,
165    /// Extra header fields, in order of them being encountered, made accessible with the iterator returned
166    /// by [`extra_headers()`](Commit::extra_headers()).
167    pub extra_headers: Vec<(BString, BString)>,
168}
169
170/// Represents a git tag, commonly indicating a software release.
171#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Copy)]
172#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
173pub struct TagRef<'a> {
174    /// The hash in hexadecimal being the object this tag points to. Use [`target()`](TagRef::target()) to obtain a byte representation.
175    #[cfg_attr(feature = "serde", serde(borrow))]
176    pub target: &'a BStr,
177    /// The kind of object that `target` points to.
178    pub target_kind: Kind,
179    /// The name of the tag, e.g. "v1.0".
180    pub name: &'a BStr,
181    /// The raw tagger header value as encountered during parsing.
182    ///
183    /// Use the [`tagger()`](TagRef::tagger()) method to obtain a parsed version of it.
184    #[cfg_attr(feature = "serde", serde(borrow))]
185    pub tagger: Option<&'a BStr>,
186    /// The message describing this release.
187    pub message: &'a BStr,
188    /// A cryptographic signature over the entire content of the serialized tag object thus far.
189    pub pgp_signature: Option<&'a BStr>,
190}
191
192/// Like [`TagRef`], but as `Iterator` to support entirely allocation free parsing.
193/// It's particularly useful to dereference only the target chain.
194#[derive(Copy, Clone)]
195pub struct TagRefIter<'a> {
196    data: &'a [u8],
197    state: tag::ref_iter::State,
198    hash_kind: gix_hash::Kind,
199}
200
201/// A mutable git tag.
202#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
203#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
204pub struct Tag {
205    /// The hash this tag is pointing to.
206    pub target: gix_hash::ObjectId,
207    /// The kind of object this tag is pointing to.
208    pub target_kind: Kind,
209    /// The name of the tag, e.g. "v1.0".
210    pub name: BString,
211    /// The tags author.
212    pub tagger: Option<gix_actor::Signature>,
213    /// The message describing the tag.
214    pub message: BString,
215    /// A pgp signature over all bytes of the encoded tag, excluding the pgp signature itself.
216    pub pgp_signature: Option<BString>,
217}
218
219/// Immutable objects are read-only structures referencing most data from [a byte slice](ObjectRef::from_bytes()).
220///
221/// Immutable objects are expected to be deserialized from bytes that acts as backing store, and they
222/// cannot be mutated or serialized. Instead, one will [convert](ObjectRef::into_owned()) them into their [`mutable`](Object) counterparts
223/// which support mutation and serialization.
224///
225/// An `ObjectRef` is representing [`Trees`](TreeRef), [`Blobs`](BlobRef), [`Commits`](CommitRef), or [`Tags`](TagRef).
226#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
227#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
228#[allow(missing_docs)]
229pub enum ObjectRef<'a> {
230    #[cfg_attr(feature = "serde", serde(borrow))]
231    Tree(TreeRef<'a>),
232    Blob(BlobRef<'a>),
233    Commit(CommitRef<'a>),
234    Tag(TagRef<'a>),
235}
236
237/// Mutable objects with each field being separately allocated and changeable.
238///
239/// Mutable objects are Commits, Trees, Blobs and Tags that can be changed and serialized.
240///
241/// They either created using object [construction](Object) or by [deserializing existing objects](ObjectRef::from_bytes())
242/// and converting these [into mutable copies](ObjectRef::into_owned()) for adjustments.
243///
244/// An `Object` is representing [`Trees`](Tree), [`Blobs`](Blob), [`Commits`](Commit), or [`Tags`](Tag).
245#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
246#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
247#[allow(clippy::large_enum_variant, missing_docs)]
248pub enum Object {
249    Tree(Tree),
250    Blob(Blob),
251    Commit(Commit),
252    Tag(Tag),
253}
254/// A directory snapshot containing files (blobs), directories (trees) and submodules (commits).
255#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
256#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
257pub struct TreeRef<'a> {
258    /// The directories and files contained in this tree.
259    ///
260    /// Beware that the sort order isn't *quite* by name, so one may bisect only with a [`tree::EntryRef`] to handle ordering correctly.
261    #[cfg_attr(feature = "serde", serde(borrow))]
262    pub entries: Vec<tree::EntryRef<'a>>,
263}
264
265/// A directory snapshot containing files (blobs), directories (trees) and submodules (commits), lazily evaluated.
266#[derive(Default, PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Copy)]
267pub struct TreeRefIter<'a> {
268    /// The hash kind to use for parsing this tree.
269    hash_kind: gix_hash::Kind,
270    /// The directories and files contained in this tree.
271    data: &'a [u8],
272}
273
274/// A mutable Tree, containing other trees, blobs or commits.
275#[derive(Default, PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
276#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
277pub struct Tree {
278    /// The directories and files contained in this tree. They must be and remain sorted by [`filename`][tree::Entry::filename].
279    ///
280    /// Beware that the sort order isn't *quite* by name, so one may bisect only with a [`tree::Entry`] to handle ordering correctly.
281    pub entries: Vec<tree::Entry>,
282}
283
284impl Tree {
285    /// Return an empty tree which serializes to a well-known hash
286    pub fn empty() -> Self {
287        Tree { entries: Vec::new() }
288    }
289}
290
291/// A borrowed object using a slice as backing buffer, or in other words a bytes buffer that knows the kind of object it represents.
292#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Copy)]
293pub struct Data<'a> {
294    /// kind of object
295    pub kind: Kind,
296    /// The hash kind to use for parsing this data.
297    pub hash_kind: gix_hash::Kind,
298    /// decoded, decompressed data, owned by a backing store.
299    pub data: &'a [u8],
300}
301
302/// Information about an object, which includes its kind and the amount of bytes it would have when obtained.
303#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Copy)]
304pub struct Header {
305    /// The kind of object.
306    pub kind: Kind,
307    /// The object's size in bytes, or the size of the buffer when it's retrieved in full.
308    pub size: u64,
309}
310
311///
312pub mod decode {
313    mod error {
314        pub(crate) fn empty_error() -> Error {
315            Error
316        }
317
318        /// A type to indicate any error occurred during parsing.
319        #[derive(Debug, Clone, Copy, Default)]
320        pub struct Error;
321
322        impl std::fmt::Display for Error {
323            fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
324                f.write_str("object parsing failed")
325            }
326        }
327
328        impl std::error::Error for Error {}
329    }
330    pub(crate) use error::empty_error;
331    pub use error::Error;
332
333    /// Returned by [`loose_header()`]
334    #[derive(Debug, thiserror::Error)]
335    #[allow(missing_docs)]
336    pub enum LooseHeaderDecodeError {
337        #[error("{message}: {number:?}")]
338        ParseIntegerError {
339            source: gix_utils::btoi::ParseIntegerError,
340            message: &'static str,
341            number: bstr::BString,
342        },
343        #[error("{message}")]
344        InvalidHeader { message: &'static str },
345        #[error("The object header contained an unknown object kind.")]
346        ObjectHeader(#[from] super::kind::Error),
347    }
348
349    use bstr::ByteSlice;
350    /// Decode a loose object header, being `<kind> <size>\0`, returns
351    /// ([`kind`](super::Kind), `size`, `consumed bytes`).
352    ///
353    /// `size` is the uncompressed size of the payload in bytes.
354    pub fn loose_header(input: &[u8]) -> Result<(super::Kind, u64, usize), LooseHeaderDecodeError> {
355        use LooseHeaderDecodeError::*;
356        let kind_end = input.find_byte(0x20).ok_or(InvalidHeader {
357            message: "Expected '<type> <size>'",
358        })?;
359        let kind = super::Kind::from_bytes(&input[..kind_end])?;
360        let size_end = input.find_byte(0x0).ok_or(InvalidHeader {
361            message: "Did not find 0 byte in header",
362        })?;
363        let size_bytes = &input[kind_end + 1..size_end];
364        let size = gix_utils::btoi::to_signed(size_bytes).map_err(|source| ParseIntegerError {
365            source,
366            message: "Object size in header could not be parsed",
367            number: size_bytes.into(),
368        })?;
369        Ok((kind, size, size_end + 1))
370    }
371}
372
373fn object_hasher(hash_kind: gix_hash::Kind, object_kind: Kind, object_size: u64) -> gix_hash::Hasher {
374    let mut hasher = gix_hash::hasher(hash_kind);
375    hasher.update(&encode::loose_header(object_kind, object_size));
376    hasher
377}
378
379/// A function to compute a hash of kind `hash_kind` for an object of `object_kind` and its `data`.
380#[doc(alias = "hash_object", alias = "git2")]
381pub fn compute_hash(
382    hash_kind: gix_hash::Kind,
383    object_kind: Kind,
384    data: &[u8],
385) -> Result<gix_hash::ObjectId, gix_hash::hasher::Error> {
386    let mut hasher = object_hasher(hash_kind, object_kind, data.len() as u64);
387    hasher.update(data);
388    hasher.try_finalize()
389}
390
391/// A function to compute a hash of kind `hash_kind` for an object of `object_kind` and its data read from `stream`
392/// which has to yield exactly `stream_len` bytes.
393/// Use `progress` to learn about progress in bytes processed and `should_interrupt` to be able to abort the operation
394/// if set to `true`.
395#[doc(alias = "hash_file", alias = "git2")]
396pub fn compute_stream_hash(
397    hash_kind: gix_hash::Kind,
398    object_kind: Kind,
399    stream: &mut dyn std::io::Read,
400    stream_len: u64,
401    progress: &mut dyn gix_features::progress::Progress,
402    should_interrupt: &std::sync::atomic::AtomicBool,
403) -> Result<gix_hash::ObjectId, gix_hash::io::Error> {
404    let hasher = object_hasher(hash_kind, object_kind, stream_len);
405    gix_hash::bytes_with_hasher(stream, stream_len, hasher, progress, should_interrupt)
406}
gix_object/lib.rs

gix_object/
lib.rs
