From b8486f7cf25c58b91ce2f40dba90d4296ddd2c07 Mon Sep 17 00:00:00 2001
From: Sebastian Thiel <sebastian.thiel@icloud.com>
Date: Mon, 8 Apr 2024 15:11:27 +0200
Subject: [PATCH] improve documentation of Topological DateOrder sorting and
 add baseline test (#1336)

---
 gix-traverse/src/commit/topo/init.rs          |   2 +-
 gix-traverse/src/commit/topo/mod.rs           |   5 ++++-
 gix-traverse/tests/commit/topo.rs             |  11 ++++++-----
 .../make_repo_for_topo.tar.xz                 | Bin 12552 -> 12584 bytes
 .../tests/fixtures/make_repo_for_topo.sh      |   1 +
 5 files changed, 12 insertions(+), 7 deletions(-)

diff --git a/gix-traverse/src/commit/topo/init.rs b/gix-traverse/src/commit/topo/init.rs
index 42972d2b871..86fb45b7321 100644
--- a/gix-traverse/src/commit/topo/init.rs
+++ b/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>>,
diff --git a/gix-traverse/src/commit/topo/mod.rs b/gix-traverse/src/commit/topo/mod.rs
index 6ae543c106c..2c39c021492 100644
--- a/gix-traverse/src/commit/topo/mod.rs
+++ b/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 `gix 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 `gix rev-list --topo-order`.
     TopoOrder,
 }
 
diff --git a/gix-traverse/tests/commit/topo.rs b/gix-traverse/tests/commit/topo.rs
index ff28a0b0c95..4486a53023f 100644
--- a/gix-traverse/tests/commit/topo.rs
+++ b/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(())
     }
 }
diff --git a/gix-traverse/tests/fixtures/generated-archives/make_repo_for_topo.tar.xz b/gix-traverse/tests/fixtures/generated-archives/make_repo_for_topo.tar.xz
index 12a8797c09727fa56608b6da1e0e8fa051d1a93d..b8ff6bed2dc7bbd4449e9e7a9c406389b094c569 100644
GIT binary patch
delta 255
zcmV<b0094pVyI$}83ZH$FzB%z9WZ|~NJEc*sbki8YQ_^3GV#u_^G5q<nLSc|Z`k*+
zdhrMXh4OsKd7u3BwXNBy1x%f^@%24H9$V)AvCrnf)l|d6>k{*|ju_Ui$%sA+t78=f
zb@AQXnSx8M<9p(LOU@W+p++xXAOG_e%S)$)pLd{5@%{q;a|tfvQacx!K=f}Xz1ph|
zlwb@f2qRq<X<ND^cCn;sjK}nP-NpoSH=_joQ+hM9>YECfH|RknJbDQTyc_xJTI3OA
z$3EKbAZ7>D+%$qIB%D@!;Mq_6kN{3r{<2!lO(FmRgkpfm1OWLG53{kvXZr#G00004
FSz2j<d{h7c

delta 223
zcmV<503iRUVu)gp83Z5yFvqbS9WZ|hy#c&au*!{=AS7V*(koIm|A57@KYkbjggHD!
zV)*qS_bg3I!f7QtFbYhQ1qNnw1pcI=qXO{ZY75bZUz3wkz6QfJSqD>5orz3<*N@qb
zjev{3<>{Zek;bxDl|hA}HqD@xZ9W^pcxcHSH;s_V<M}KHeeWzzmkz-5pM_8B0yraf
zgtjdG1wqMm2TE;~C@e5s+CJrU7Jg~feq~_oQM@FLT|iHKGu+e=006>=;+()Iuq*%p
Z<6(fn1ORgeP4BV9XZr#G00004Sz1mHV{rfg

diff --git a/gix-traverse/tests/fixtures/make_repo_for_topo.sh b/gix-traverse/tests/fixtures/make_repo_for_topo.sh
index 6550da2e2c0..6a04778bb75 100755
--- a/gix-traverse/tests/fixtures/make_repo_for_topo.sh
+++ b/gix-traverse/tests/fixtures/make_repo_for_topo.sh
@@ -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