Merge pull request GitoxideLabs#1716 from neithernut/traverse-topo-builder-enhancements

Enhance builder-likeness of `commit::topo::Builder` in `gix-traverse`

Author: Byron

gix-traverse/src/commit/topo/init.rs

@@ -28,22 +28,40 @@ where
         tips: impl IntoIterator<Item = impl Into<ObjectId>>,
         ends: Option<impl IntoIterator<Item = impl Into<ObjectId>>>,
     ) -> Self {
-        let tips = tips.into_iter().map(Into::into).collect::<Vec<_>>();
-        let ends = ends
-            .map(|e| e.into_iter().map(Into::into).collect::<Vec<_>>())
-            .unwrap_or_default();
+        Self::new(find).with_tips(tips).with_ends(ends.into_iter().flatten())
+    }
 
+    /// Create a new `Builder` for a [`Topo`] that reads commits from a
+    /// repository with `find`.
+    pub fn new(find: Find) -> Self {
         Self {
             commit_graph: Default::default(),
             find,
             sorting: Default::default(),
             parents: Default::default(),
-            tips,
-            ends,
+            tips: Default::default(),
+            ends: Default::default(),
             predicate: |_| true,
         }
     }
 
+    /// Add commits to start reading from.
+    ///
+    /// The behavior is similar to specifying additional `ends` in `git rev-list --topo-order ^ends tips`.
+    pub fn with_tips(mut self, tips: impl IntoIterator<Item = impl Into<ObjectId>>) -> Self {
+        self.tips.extend(tips.into_iter().map(Into::into));
+        self
+    }
+
+    /// Add commits ending the traversal.
+    ///
+    /// These commits themselves will not be read, i.e. the behavior is similar to specifying additional
+    /// `ends` in `git rev-list --topo-order ^ends tips`.
+    pub fn with_ends(mut self, ends: impl IntoIterator<Item = impl Into<ObjectId>>) -> Self {
+        self.ends.extend(ends.into_iter().map(Into::into));
+        self
+    }
+
     /// Set a `predicate` to filter out revisions from the walk. Can be used to
     /// implement e.g. filtering on paths or time. This does *not* exclude the
     /// parent(s) of a revision that is excluded. Specify a revision as an 'end'