feat: revision::walk::Platform::selected(filter) to selectively prune parts of the commit graph. (#801)

Author: Byron

gix/src/revision/walk.rs

@@ -50,13 +50,14 @@ impl<'repo> Platform<'repo> {
 
 /// Produce the iterator
 impl<'repo> Platform<'repo> {
-    /// Return an iterator to traverse all commits reachable as configured by the [Platform].
-    ///
-    /// # Performance
+    /// For each commit, let `filter` return `true` if it and its parents should be included in the traversal, or `false`
+    /// if the traversal should exclude it and its ancestry entirely.
     ///
-    /// It's highly recommended to set an [`object cache`][Repository::object_cache_size()] on the parent repo
-    /// to greatly speed up performance if the returned id is supposed to be looked up right after.
-    pub fn all(self) -> Result<revision::Walk<'repo>, Error> {
+    /// If `filter` is None, no pruning of the graph will be performed which is the default.
+    pub fn selected(
+        self,
+        mut filter: impl FnMut(&gix_hash::oid) -> bool + 'repo,
+    ) -> Result<revision::Walk<'repo>, Error> {
         let Platform {
             repo,
             tips,
@@ -74,22 +75,27 @@ impl<'repo> Platform<'repo> {
                         let shallow_commits = repo.shallow_commits()?;
                         let mut grafted_parents_to_skip = Vec::new();
                         let mut buf = Vec::new();
-                        move |id| match shallow_commits.as_ref() {
-                            Some(commits) => {
-                                let id = id.to_owned();
-                                if let Ok(idx) = grafted_parents_to_skip.binary_search(&id) {
-                                    grafted_parents_to_skip.remove(idx);
-                                    return false;
-                                };
-                                if commits.binary_search(&id).is_ok() {
-                                    if let Ok(commit) = repo.objects.find_commit_iter(id, &mut buf) {
-                                        grafted_parents_to_skip.extend(commit.parent_ids());
-                                        grafted_parents_to_skip.sort();
-                                    }
-                                };
-                                true
+                        move |id| {
+                            if !filter(id) {
+                                return false;
+                            }
+                            match shallow_commits.as_ref() {
+                                Some(commits) => {
+                                    let id = id.to_owned();
+                                    if let Ok(idx) = grafted_parents_to_skip.binary_search(&id) {
+                                        grafted_parents_to_skip.remove(idx);
+                                        return false;
+                                    };
+                                    if commits.binary_search(&id).is_ok() {
+                                        if let Ok(commit) = repo.objects.find_commit_iter(id, &mut buf) {
+                                            grafted_parents_to_skip.extend(commit.parent_ids());
+                                            grafted_parents_to_skip.sort();
+                                        }
+                                    };
+                                    true
+                                }
+                                None => true,
                             }
-                            None => true,
                         }
                     },
                 )
@@ -98,6 +104,15 @@ impl<'repo> Platform<'repo> {
             ),
         })
     }
+    /// Return an iterator to traverse all commits reachable as configured by the [Platform].
+    ///
+    /// # Performance
+    ///
+    /// It's highly recommended to set an [`object cache`][Repository::object_cache_size()] on the parent repo
+    /// to greatly speed up performance if the returned id is supposed to be looked up right after.
+    pub fn all(self) -> Result<revision::Walk<'repo>, Error> {
+        self.selected(|_| true)
+    }
 }
 
 pub(crate) mod iter {

gix/tests/id/mod.rs

@@ -67,6 +67,7 @@ fn display_and_debug() -> crate::Result {
 }
 
 mod ancestors {
+    use crate::id::hex_to_id;
     use gix_traverse::commit;
 
     #[test]
@@ -98,4 +99,34 @@ mod ancestors {
         );
         Ok(())
     }
+
+    #[test]
+    fn filtered() -> crate::Result {
+        let repo = crate::repo("make_repo_with_fork_and_dates.sh")?.to_thread_local();
+        let head = repo.head()?.into_fully_peeled_id().expect("born")?;
+
+        for sorting in [
+            commit::Sorting::Topological,
+            commit::Sorting::ByCommitTimeNewestFirst,
+            commit::Sorting::ByCommitTimeNewestFirstCutoffOlderThan {
+                time_in_seconds_since_epoch: 0,
+            },
+        ] {
+            let commits_graph_order = head
+                .ancestors()
+                .sorting(sorting)
+                .selected(|id| {
+                    let _assert_lifetime_works = &repo; // assure we can use repo here.
+                    id != hex_to_id("9902e3c3e8f0c569b4ab295ddf473e6de763e1e7")
+                        && id != hex_to_id("bcb05040a6925f2ff5e10d3ae1f9264f2e8c43ac")
+                })?
+                .collect::<Result<Vec<_>, _>>()?;
+            assert_eq!(
+                commits_graph_order,
+                &[hex_to_id("288e509293165cb5630d08f4185bdf2445bf6170")],
+                "we ignore all but the first"
+            );
+        }
+        Ok(())
+    }
 }