improve documentation of Topological DateOrder sorting and add baseline test (#1336)

Author: Byron

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

@@ -22,7 +22,7 @@ where
 {
     /// Create a new `Builder` for a [`Topo`] that reads commits from a repository with `find`.
     /// starting at the `tips` and ending at the `ends`. Like `git rev-list
-    /// --topo-order ^ends... tips...`.
+    /// --topo-order ^ends tips`.
     pub fn from_iters(
         find: Find,
         tips: impl IntoIterator<Item = impl Into<ObjectId>>,

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

@@ -55,12 +55,15 @@ bitflags! {
 pub enum Sorting {
     /// Show no parents before all of its children are shown, but otherwise show
     /// commits in the commit timestamp order.
+    ///
+    /// This is equivalent to `git rev-list --date-order`.
     #[default]
     DateOrder,
     /// Show no parents before all of its children are shown, and avoid
     /// showing commits on multiple lines of history intermixed.
     ///
-    /// In the *sample history* the order would be `8, 6, 5, 3, 7, 4, 2, 1`
+    /// In the *sample history* the order would be `8, 6, 5, 3, 7, 4, 2, 1`.
+    /// This is equivalent to `git rev-list --topo-order`.
     TopoOrder,
 }
 

gix-traverse/tests/commit/topo.rs

@@ -346,8 +346,8 @@ mod date_order {
     use super::TraversalAssertion;
 
     #[test]
-    fn simple() -> crate::Result {
-        TraversalAssertion::new(
+    fn with_ends() -> crate::Result {
+        let mut assertion = TraversalAssertion::new(
             // Same tip and end as basic::one_end() but the order should be
             // different.
             &["62ed296d9986f50477e9f7b7e81cd0258939a43d"],
@@ -365,8 +365,9 @@ mod date_order {
                 "33eb18340e4eaae3e3dcf80222b02f161cd3f966",
                 "1a27cb1a26c9faed9f0d1975326fe51123ab01ed",
             ],
-        )
-        .with_sorting(topo::Sorting::DateOrder)
-        .check()
+        );
+        assertion.with_sorting(topo::Sorting::DateOrder).check()?;
+        assertion.assert_baseline("date-order");
+        Ok(())
     }
 }

gix-traverse/tests/fixtures/generated-archives/make_repo_for_topo.tar.xz

@@ -28,6 +28,7 @@ function optimize() {
 function collect_baselines() {
   git rev-list --topo-order HEAD > all-commits.baseline
   git rev-list --topo-order --first-parent HEAD > first-parent.baseline
+  git rev-list --date-order ^f1cce1b5c7efcdfa106e95caa6c45a2cae48a481 HEAD > date-order.baseline
 }
 
 git init