gix_commitgraph/file/
commit.rs

1//! Low-level operations on individual commits.
2use crate::{
3    file::{self, EXTENDED_EDGES_MASK, LAST_EXTENDED_EDGE_MASK, NO_PARENT},
4    File, Position,
5};
6use gix_error::{message, Message};
7use std::{
8    fmt::{Debug, Formatter},
9    slice::Chunks,
10};
11
12/// A commit as stored in a [`File`].
13#[derive(Copy, Clone)]
14pub struct Commit<'a> {
15    file: &'a File,
16    pos: file::Position,
17    // We can parse the below fields lazily if needed.
18    commit_timestamp: u64,
19    generation: u32,
20    parent1: ParentEdge,
21    parent2: ParentEdge,
22    root_tree_id: &'a gix_hash::oid,
23}
24
25#[inline]
26fn read_u32(b: &[u8]) -> u32 {
27    u32::from_be_bytes(b.try_into().unwrap())
28}
29
30impl<'a> Commit<'a> {
31    pub(crate) fn new(file: &'a File, pos: file::Position) -> Self {
32        let bytes = file.commit_data_bytes(pos);
33        Commit {
34            file,
35            pos,
36            root_tree_id: gix_hash::oid::from_bytes_unchecked(&bytes[..file.hash_len]),
37            parent1: ParentEdge::from_raw(read_u32(&bytes[file.hash_len..][..4])),
38            parent2: ParentEdge::from_raw(read_u32(&bytes[file.hash_len + 4..][..4])),
39            // TODO: Add support for corrected commit date offset overflow.
40            //      See https://github.com/git/git/commit/e8b63005c48696a26f976f5f9b0ccaf1983e439d and
41            //          https://github.com/git/git/commit/f90fca638e99a031dce8e3aca72427b2f9b4bb38 for more details and hints at a test.
42            generation: read_u32(&bytes[file.hash_len + 8..][..4]) >> 2,
43            commit_timestamp: u64::from_be_bytes(bytes[file.hash_len + 8..][..8].try_into().unwrap())
44                & 0x0003_ffff_ffff,
45        }
46    }
47
48    /// Returns the committer timestamp of this commit.
49    ///
50    /// The value is the number of seconds since 1970-01-01 00:00:00 UTC.
51    pub fn committer_timestamp(&self) -> u64 {
52        self.commit_timestamp
53    }
54
55    /// Returns the generation number of this commit.
56    ///
57    /// Commits without parents have generation number 1. Commits with parents have a generation
58    /// number that is the max of their parents' generation numbers + 1.
59    pub fn generation(&self) -> u32 {
60        self.generation
61    }
62
63    /// Returns an iterator over the parent positions for lookup in the owning [Graph][crate::Graph].
64    pub fn iter_parents(self) -> Parents<'a> {
65        // I didn't find a combinator approach that a) was as strict as ParentIterator, b) supported
66        // fuse-after-first-error behavior, and b) was significantly shorter or more understandable
67        // than ParentIterator. So here we are.
68        Parents {
69            commit_data: self,
70            state: ParentIteratorState::First,
71        }
72    }
73
74    /// Returns the hash of this commit.
75    pub fn id(&self) -> &'a gix_hash::oid {
76        self.file.id_at(self.pos)
77    }
78
79    /// Returns the first parent of this commit.
80    pub fn parent1(&self) -> Result<Option<Position>, Message> {
81        self.iter_parents().next().transpose()
82    }
83
84    /// Returns the position at which this commit is stored in the parent [File].
85    pub fn position(&self) -> file::Position {
86        self.pos
87    }
88
89    /// Return the hash of the tree this commit points to.
90    pub fn root_tree_id(&self) -> &gix_hash::oid {
91        self.root_tree_id
92    }
93}
94
95impl Debug for Commit<'_> {
96    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
97        write!(
98            f,
99            "Commit {{ id: {}, lex_pos: {}, generation: {}, root_tree_id: {}, parent1: {:?}, parent2: {:?} }}",
100            self.id(),
101            self.pos,
102            self.generation(),
103            self.root_tree_id(),
104            self.parent1,
105            self.parent2,
106        )
107    }
108}
109
110impl Eq for Commit<'_> {}
111
112impl PartialEq for Commit<'_> {
113    fn eq(&self, other: &Self) -> bool {
114        std::ptr::eq(self.file, other.file) && self.pos == other.pos
115    }
116}
117
118/// An iterator over parents of a [`Commit`].
119pub struct Parents<'a> {
120    commit_data: Commit<'a>,
121    state: ParentIteratorState<'a>,
122}
123
124impl Iterator for Parents<'_> {
125    type Item = Result<Position, Message>;
126
127    fn next(&mut self) -> Option<Self::Item> {
128        let state = std::mem::replace(&mut self.state, ParentIteratorState::Exhausted);
129        match state {
130            ParentIteratorState::First => match self.commit_data.parent1 {
131                ParentEdge::None => match self.commit_data.parent2 {
132                    ParentEdge::None => None,
133                    _ => Some(Err(message!(
134                        "commit {} has a second parent but not a first parent",
135                        self.commit_data.id()
136                    ))),
137                },
138                ParentEdge::GraphPosition(pos) => {
139                    self.state = ParentIteratorState::Second;
140                    Some(Ok(pos))
141                }
142                ParentEdge::ExtraEdgeIndex(_) => Some(Err(message!(
143                    "commit {}'s first parent is an extra edge index, which is invalid",
144                    self.commit_data.id(),
145                ))),
146            },
147            ParentIteratorState::Second => match self.commit_data.parent2 {
148                ParentEdge::None => None,
149                ParentEdge::GraphPosition(pos) => Some(Ok(pos)),
150                ParentEdge::ExtraEdgeIndex(extra_edge_index) => {
151                    if let Some(extra_edges_list) = self.commit_data.file.extra_edges_data() {
152                        let start_offset: usize = extra_edge_index
153                            .try_into()
154                            .expect("an architecture able to hold 32 bits of integer");
155                        let start_offset = start_offset
156                            .checked_mul(4)
157                            .expect("an extended edge index small enough to fit in usize");
158                        if let Some(tail) = extra_edges_list.get(start_offset..) {
159                            self.state = ParentIteratorState::Extra(tail.chunks(4));
160                            // This recursive call is what blocks me from replacing ParentIterator
161                            // with a std::iter::from_fn closure.
162                            self.next()
163                        } else {
164                            Some(Err(message!(
165                                "commit {}'s extra edges overflows the commit-graph file's extra edges list",
166                                self.commit_data.id()
167                            )))
168                        }
169                    } else {
170                        Some(Err(message!(
171                            "commit {} has extra edges, but commit-graph file has no extra edges list",
172                            self.commit_data.id()
173                        )))
174                    }
175                }
176            },
177            ParentIteratorState::Extra(mut chunks) => {
178                if let Some(chunk) = chunks.next() {
179                    let extra_edge = read_u32(chunk);
180                    match ExtraEdge::from_raw(extra_edge) {
181                        ExtraEdge::Internal(pos) => {
182                            self.state = ParentIteratorState::Extra(chunks);
183                            Some(Ok(pos))
184                        }
185                        ExtraEdge::Last(pos) => Some(Ok(pos)),
186                    }
187                } else {
188                    Some(Err(message!(
189                        "commit {}'s extra edges overflows the commit-graph file's extra edges list",
190                        self.commit_data.id()
191                    )))
192                }
193            }
194            ParentIteratorState::Exhausted => None,
195        }
196    }
197
198    fn size_hint(&self) -> (usize, Option<usize>) {
199        match (&self.state, self.commit_data.parent1, self.commit_data.parent2) {
200            (ParentIteratorState::First, ParentEdge::None, ParentEdge::None) => (0, Some(0)),
201            (ParentIteratorState::First, ParentEdge::None, _) => (1, Some(1)),
202            (ParentIteratorState::First, ParentEdge::GraphPosition(_), ParentEdge::None) => (1, Some(1)),
203            (ParentIteratorState::First, ParentEdge::GraphPosition(_), ParentEdge::GraphPosition(_)) => (2, Some(2)),
204            (ParentIteratorState::First, ParentEdge::GraphPosition(_), ParentEdge::ExtraEdgeIndex(_)) => (3, None),
205            (ParentIteratorState::First, ParentEdge::ExtraEdgeIndex(_), _) => (1, Some(1)),
206            (ParentIteratorState::Second, _, ParentEdge::None) => (0, Some(0)),
207            (ParentIteratorState::Second, _, ParentEdge::GraphPosition(_)) => (1, Some(1)),
208            (ParentIteratorState::Second, _, ParentEdge::ExtraEdgeIndex(_)) => (2, None),
209            (ParentIteratorState::Extra(_), _, _) => (1, None),
210            (ParentIteratorState::Exhausted, _, _) => (0, Some(0)),
211        }
212    }
213}
214
215#[derive(Debug)]
216enum ParentIteratorState<'a> {
217    First,
218    Second,
219    Extra(Chunks<'a, u8>),
220    Exhausted,
221}
222
223#[derive(Clone, Copy, Debug)]
224enum ParentEdge {
225    None,
226    GraphPosition(Position),
227    ExtraEdgeIndex(u32),
228}
229
230impl ParentEdge {
231    pub fn from_raw(raw: u32) -> ParentEdge {
232        if raw == NO_PARENT {
233            return ParentEdge::None;
234        }
235        if raw & EXTENDED_EDGES_MASK != 0 {
236            ParentEdge::ExtraEdgeIndex(raw & !EXTENDED_EDGES_MASK)
237        } else {
238            ParentEdge::GraphPosition(Position(raw))
239        }
240    }
241}
242
243enum ExtraEdge {
244    Internal(Position),
245    Last(Position),
246}
247
248impl ExtraEdge {
249    pub fn from_raw(raw: u32) -> Self {
250        if raw & LAST_EXTENDED_EDGE_MASK != 0 {
251            Self::Last(Position(raw & !LAST_EXTENDED_EDGE_MASK))
252        } else {
253            Self::Internal(Position(raw))
254        }
255    }
256}
gix_commitgraph/file/commit.rs

gix_commitgraph/file/
commit.rs
