gix_object/commit/
mod.rs

1use std::ops::Range;
2
3use bstr::{BStr, BString, ByteSlice};
4use winnow::prelude::*;
5
6use crate::{Commit, CommitRef, TagRef};
7
8mod decode;
9///
10pub mod message;
11
12/// A parsed commit message that assumes a title separated from the body by two consecutive newlines.
13///
14/// Titles can have any amount of whitespace
15#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Copy)]
16#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
17pub struct MessageRef<'a> {
18    /// The title of the commit, as separated from the body with two consecutive newlines. The newlines are not included.
19    #[cfg_attr(feature = "serde", serde(borrow))]
20    pub title: &'a BStr,
21    /// All bytes not consumed by the title, excluding the separating newlines.
22    ///
23    /// The body is `None` if there was now title separation or the body was empty after the separator.
24    pub body: Option<&'a BStr>,
25}
26
27/// The raw commit data, parseable by [`CommitRef`] or [`Commit`], which was fed into a program to produce a signature.
28///
29/// See [`extract_signature()`](crate::CommitRefIter::signature()) for how to obtain it.
30// TODO: implement `std::io::Read` to avoid allocations
31#[derive(PartialEq, Eq, Debug, Hash, Clone)]
32#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
33pub struct SignedData<'a> {
34    /// The raw commit data that includes the signature.
35    data: &'a [u8],
36    /// The byte range at which we find the signature. All but the signature is the data that was signed.
37    signature_range: Range<usize>,
38}
39
40impl SignedData<'_> {
41    /// Convenience method to obtain a copy of the signed data.
42    pub fn to_bstring(&self) -> BString {
43        let mut buf = BString::from(&self.data[..self.signature_range.start]);
44        buf.extend_from_slice(&self.data[self.signature_range.end..]);
45        buf
46    }
47}
48
49impl From<SignedData<'_>> for BString {
50    fn from(value: SignedData<'_>) -> Self {
51        value.to_bstring()
52    }
53}
54
55///
56pub mod ref_iter;
57
58mod write;
59
60/// Lifecycle
61impl<'a> CommitRef<'a> {
62    /// Deserialize a commit from the given `data` bytes while avoiding most allocations.
63    pub fn from_bytes(mut data: &'a [u8]) -> Result<CommitRef<'a>, crate::decode::Error> {
64        let input = &mut data;
65        match decode::commit.parse_next(input) {
66            Ok(tag) => Ok(tag),
67            Err(err) => Err(crate::decode::Error::with_err(err, input)),
68        }
69    }
70}
71
72/// Access
73impl<'a> CommitRef<'a> {
74    /// Return the `tree` fields hash digest.
75    pub fn tree(&self) -> gix_hash::ObjectId {
76        gix_hash::ObjectId::from_hex(self.tree).expect("prior validation of tree hash during parsing")
77    }
78
79    /// Returns an iterator of parent object ids
80    pub fn parents(&self) -> impl Iterator<Item = gix_hash::ObjectId> + '_ {
81        self.parents
82            .iter()
83            .map(|hex_hash| gix_hash::ObjectId::from_hex(hex_hash).expect("prior validation of hashes during parsing"))
84    }
85
86    /// Returns a convenient iterator over all extra headers.
87    pub fn extra_headers(&self) -> crate::commit::ExtraHeaders<impl Iterator<Item = (&BStr, &BStr)>> {
88        ExtraHeaders::new(self.extra_headers.iter().map(|(k, v)| (*k, v.as_ref())))
89    }
90
91    /// Return the author, with whitespace trimmed.
92    ///
93    /// This is different from the `author` field which may contain whitespace.
94    pub fn author(&self) -> gix_actor::SignatureRef<'a> {
95        self.author.trim()
96    }
97
98    /// Return the committer, with whitespace trimmed.
99    ///
100    /// This is different from the `committer` field which may contain whitespace.
101    pub fn committer(&self) -> gix_actor::SignatureRef<'a> {
102        self.committer.trim()
103    }
104
105    /// Returns a partially parsed message from which more information can be derived.
106    pub fn message(&self) -> MessageRef<'a> {
107        MessageRef::from_bytes(self.message)
108    }
109
110    /// Returns the time at which this commit was created.
111    pub fn time(&self) -> gix_date::Time {
112        self.committer.time
113    }
114}
115
116impl Commit {
117    /// Returns a convenient iterator over all extra headers.
118    pub fn extra_headers(&self) -> ExtraHeaders<impl Iterator<Item = (&BStr, &BStr)>> {
119        ExtraHeaders::new(self.extra_headers.iter().map(|(k, v)| (k.as_bstr(), v.as_bstr())))
120    }
121}
122
123/// An iterator over extra headers in [owned][crate::Commit] and [borrowed][crate::CommitRef] commits.
124pub struct ExtraHeaders<I> {
125    inner: I,
126}
127
128/// Instantiation and convenience.
129impl<'a, I> ExtraHeaders<I>
130where
131    I: Iterator<Item = (&'a BStr, &'a BStr)>,
132{
133    /// Create a new instance from an iterator over tuples of (name, value) pairs.
134    pub fn new(iter: I) -> Self {
135        ExtraHeaders { inner: iter }
136    }
137    /// Find the _value_ of the _first_ header with the given `name`.
138    pub fn find(mut self, name: &str) -> Option<&'a BStr> {
139        self.inner
140            .find_map(move |(k, v)| if k == name.as_bytes().as_bstr() { Some(v) } else { None })
141    }
142    /// Return an iterator over all _values_ of headers with the given `name`.
143    pub fn find_all(self, name: &'a str) -> impl Iterator<Item = &'a BStr> {
144        self.inner
145            .filter_map(move |(k, v)| if k == name.as_bytes().as_bstr() { Some(v) } else { None })
146    }
147    /// Return an iterator over all git mergetags.
148    ///
149    /// A merge tag is a tag object embedded within the respective header field of a commit, making
150    /// it a child object of sorts.
151    pub fn mergetags(self) -> impl Iterator<Item = Result<TagRef<'a>, crate::decode::Error>> {
152        self.find_all("mergetag").map(|b| TagRef::from_bytes(b))
153    }
154
155    /// Return the cryptographic signature provided by gpg/pgp verbatim.
156    pub fn pgp_signature(self) -> Option<&'a BStr> {
157        self.find("gpgsig")
158    }
159}
gix_object/commit/mod.rs

gix_object/commit/
mod.rs
