grit_lib/revwalk/
handle.rs

1//! Repository-scoped revision parsing and walking via [`RevWalk`].
2use crate::error::Result;
3use crate::object_inspect::{ResolveError, ResolvedObject};
4use crate::objects::ObjectId;
5use crate::repo::Repository;
6use crate::rev_list::{
7    open_commit_stream, rev_list, CommitExtent, CommitStreamParams, RevListOptions, RevListResult,
8};
9use crate::rev_list_error::RevListError;
10use crate::rev_parse::resolve_revision;
11use crate::revwalk::parse_rev_walk_tokens;
12use crate::revwalk::RevWalkCommitIterOptions;
13use std::borrow::Cow;
14
15/// Parse revision specs and walk commit history for one repository.
16#[derive(Debug, Copy, Clone)]
17pub struct RevWalk<'repo> {
18    repo: &'repo Repository,
19}
20
21impl<'repo> RevWalk<'repo> {
22    /// Bind rev-parse and rev-list to `repo`.
23    #[inline]
24    #[must_use]
25    pub fn new(repo: &'repo Repository) -> Self {
26        Self { repo }
27    }
28
29    /// Underlying repository.
30    #[inline]
31    #[must_use]
32    pub fn repository(&self) -> &'repo Repository {
33        self.repo
34    }
35
36    /// Resolve a user revision spec (for example `HEAD`, `main~2`, `v1.0`).
37    ///
38    /// # Errors
39    ///
40    /// Propagates rev-parse and ref errors.
41    ///
42    /// # Examples
43    ///
44    /// ```
45    /// # fn main() -> grit_lib::error::Result<()> {
46    /// use grit_lib::repo::{InitOptions, Repository};
47    /// use grit_lib::ident::Signature;
48    /// use grit_lib::porcelain::commit::{create_commit, CommitRequest};
49    /// use grit_lib::progress::NullProgress;
50    /// let dir = std::env::temp_dir().join("grit-revwalk-parse-doc");
51    /// let repo = Repository::init(&dir, &InitOptions::default())?;
52    /// let mut req = CommitRequest::new("doc");
53    /// req.author = Some(Signature::new("Doc", "doc@example.com", repo.identity_now())?);
54    /// req.committer = Some(Signature::new("Doc", "doc@example.com", repo.identity_now())?);
55    /// req.allow_empty = true;
56    /// let _ = create_commit(&repo, &req, &mut NullProgress, &grit_lib::progress::NeverCancel)?;
57    /// let _ = repo.rev_walk().resolve("refs/heads/main")?;
58    /// # Ok(())
59    /// # }
60    /// ```
61    #[inline]
62    pub fn resolve(&self, spec: &str) -> Result<ObjectId> {
63        resolve_revision(self.repo, spec)
64    }
65
66    /// Resolve `spec` to oid, kind, size, and optional ref name ([`ResolvedObject`]).
67    ///
68    /// # Errors
69    ///
70    /// See [`Repository::resolve`].
71    #[inline]
72    pub fn resolve_object(&self, spec: &str) -> std::result::Result<ResolvedObject, ResolveError> {
73        self.repo.resolve(spec)
74    }
75
76    /// Walk commits matching one revision `spec`: a plain tip (`main`, `HEAD~3`), an exclusion
77    /// (`^tip`), a range (`A..B`), or a symmetric difference (`A...B`, like `git rev-list A...B`).
78    /// Either side of a range may be empty and defaults to `HEAD`.
79    ///
80    /// This is the low-level entry point: it takes the [`rev_list`] engine's full
81    /// [`RevListOptions`]. For several tokens, ref selections (`--all`, `--branches`), or path
82    /// limits use [`RevWalk::commits`] / [`RevWalk::rev_list_result`] with
83    /// [`RevWalkListOptions`](crate::revwalk::RevWalkListOptions). For `A...B`,
84    /// `symmetric_left` / `symmetric_right` are filled from the range unless already set, so
85    /// `left_right`, `left_only`, and `right_only` work as in Git.
86    ///
87    /// Commit-graph acceleration and bounded `-n` early-stop apply with
88    /// [`RevListOptions::default`].
89    ///
90    /// # Errors
91    ///
92    /// - [`RevListError::UnsupportedWalkSpec`] when `spec` starts with `-` (an option or `--`)
93    ///   or holds several whitespace-separated tokens.
94    /// - Rev-parse, merge-base, and rev-list errors otherwise.
95    ///
96    /// # Examples
97    ///
98    /// See the library guide page on [revision walking](https://grit-scm.com/docs/library/revwalk/).
99    pub fn walk(&self, spec: &str, options: &RevListOptions) -> Result<RevListResult> {
100        if !is_single_walk_spec(spec) {
101            return Err(RevListError::UnsupportedWalkSpec {
102                spec: spec.to_owned(),
103            }
104            .into());
105        }
106        let parsed = parse_rev_walk_tokens(self.repo, &[spec])?;
107        let options = if parsed.symmetric_left.is_some()
108            && (options.symmetric_left.is_none() || options.symmetric_right.is_none())
109        {
110            let mut symmetric = options.clone();
111            symmetric.symmetric_left = symmetric.symmetric_left.or(parsed.symmetric_left);
112            symmetric.symmetric_right = symmetric.symmetric_right.or(parsed.symmetric_right);
113            Cow::Owned(symmetric)
114        } else {
115            Cow::Borrowed(options)
116        };
117        rev_list(self.repo, &parsed.positive, &parsed.negative, &options)
118    }
119
120    /// Lazy commit-only iterator for one revision `spec` (same single-token rules as [`Self::walk`]).
121    ///
122    /// Yields commits in default date order without building [`RevListResult`] object/cherry tables.
123    /// Use [`RevWalkCommitIterOptions`] for `skip`, `limit`, date cutoffs, and `first_parent`; for
124    /// path limits, filters, or symmetric diff metadata use [`RevWalk::commits`] with
125    /// [`crate::revwalk::RevWalkListOptions`].
126    ///
127    /// # Errors
128    ///
129    /// Same as [`Self::walk`] for invalid specs; setup errors are returned from [`RevWalkCommitIter::next`].
130    pub fn commits_iter(
131        &self,
132        spec: &str,
133        options: &RevWalkCommitIterOptions,
134    ) -> Result<RevWalkCommitIter<'repo>> {
135        if !is_single_walk_spec(spec) {
136            return Err(RevListError::UnsupportedWalkSpec {
137                spec: spec.to_owned(),
138            }
139            .into());
140        }
141        let parsed = parse_rev_walk_tokens(self.repo, &[spec])?;
142        let include =
143            crate::rev_list::resolve_specs_for_commit_stream(self.repo, &parsed.positive)?;
144        let exclude =
145            crate::rev_list::resolve_specs_for_commit_stream(self.repo, &parsed.negative)?;
146        let params = CommitStreamParams {
147            skip: options.skip,
148            limit: options.limit,
149            since: options.since,
150            until: options.until,
151            first_parent: options.first_parent,
152            retain_commit_bytes: false,
153            retained_commit_extent: CommitExtent::Whole,
154        };
155        Ok(RevWalkCommitIter {
156            inner: open_commit_stream(self.repo, &include, &exclude, &params)?,
157        })
158    }
159}
160
161/// Iterator over commits from [`RevWalk::commits_iter`].
162pub struct RevWalkCommitIter<'repo> {
163    inner: crate::rev_list::CommitStream<'repo>,
164}
165
166impl Iterator for RevWalkCommitIter<'_> {
167    type Item = Result<ObjectId>;
168
169    fn next(&mut self) -> Option<Self::Item> {
170        self.inner.next().map(|item| item.map(|row| row.oid))
171    }
172}
173
174/// Whether `spec` can be one revision expression rather than an option or a token list.
175///
176/// Whitespace is legal inside `@{...}` / `^{...}` (reflog dates, message searches) and after a
177/// `:` (`:/message`, `rev:path`), so only whitespace outside those forms marks several tokens.
178fn is_single_walk_spec(spec: &str) -> bool {
179    if spec.starts_with('-') {
180        return false;
181    }
182    let mut brace_depth = 0usize;
183    for c in spec.chars() {
184        match c {
185            ':' if brace_depth == 0 => return true,
186            '{' => brace_depth += 1,
187            '}' => brace_depth = brace_depth.saturating_sub(1),
188            c if c.is_whitespace() && brace_depth == 0 => return false,
189            _ => {}
190        }
191    }
192    true
193}
194
195#[cfg(test)]
196mod commit_iter_tests {
197    use super::*;
198    use crate::ident::Signature;
199    use crate::porcelain::commit::{create_commit, CommitRequest};
200    use crate::progress::{NeverCancel, NullProgress};
201    use crate::repo::{InitOptions, Repository};
202
203    fn init_repo_with_commits(count: usize) -> (tempfile::TempDir, Repository) {
204        let dir = tempfile::tempdir().expect("tempdir");
205        let repo = Repository::init(dir.path(), &InitOptions::default()).expect("init");
206        for i in 0..count {
207            let mut req = CommitRequest::new(format!("commit {i}"));
208            req.author = Some(
209                Signature::new("Author", "a@example.com", repo.identity_now()).expect("author"),
210            );
211            req.committer = Some(
212                Signature::new("Committer", "c@example.com", repo.identity_now())
213                    .expect("committer"),
214            );
215            req.allow_empty = true;
216            create_commit(&repo, &req, &mut NullProgress, &NeverCancel).expect("commit");
217        }
218        (dir, repo)
219    }
220
221    #[test]
222    fn commits_iter_stops_at_limit_without_full_rev_list() {
223        let (_dir, repo) = init_repo_with_commits(5);
224        let options = RevWalkCommitIterOptions {
225            limit: Some(2),
226            ..RevWalkCommitIterOptions::default()
227        };
228        let ids: Vec<_> = repo
229            .rev_walk()
230            .commits_iter("HEAD", &options)
231            .expect("iter")
232            .collect::<Result<Vec<_>>>()
233            .expect("walk");
234        assert_eq!(ids.len(), 2);
235    }
236
237    #[test]
238    fn commits_iter_since_cutoff_filters_old_commits() {
239        let (_dir, repo) = init_repo_with_commits(4);
240        let newest = repo.rev_walk().resolve("HEAD").expect("head");
241        let params = crate::rev_list::CommitStreamParams {
242            limit: Some(10),
243            ..Default::default()
244        };
245        let all: Vec<_> = open_commit_stream(&repo, std::slice::from_ref(&newest), &[], &params)
246            .expect("stream")
247            .map(|item| item.map(|row| row.oid))
248            .collect::<Result<Vec<_>>>()
249            .expect("walk");
250        assert_eq!(all.len(), 4);
251
252        let future = i64::MAX;
253        let filtered: Vec<_> = open_commit_stream(
254            &repo,
255            std::slice::from_ref(&newest),
256            &[],
257            &crate::rev_list::CommitStreamParams {
258                since: Some(future),
259                ..Default::default()
260            },
261        )
262        .expect("stream")
263        .map(|item| item.map(|row| row.oid))
264        .collect::<Result<Vec<_>>>()
265        .expect("walk");
266        assert!(filtered.is_empty());
267    }
268}
grit_lib/revwalk/handle.rs

grit_lib/revwalk/
handle.rs
