From b78e7dd99230077b694434e0ed7d236f97aba046 Mon Sep 17 00:00:00 2001
From: Sebastian Thiel <sebastian.thiel@icloud.com>
Date: Thu, 30 Jan 2025 16:53:08 +0100
Subject: [PATCH] fix!: make clear what `with_pruned()` is doing by renaming it
 to `with_boundary()`.

This is how it acts, and it's not at all the same as `hide()` in `git2`.
---
 gix/src/revision/walk.rs | 29 +++++++++++++++--------------
 gix/tests/gix/id.rs      |  2 +-
 2 files changed, 16 insertions(+), 15 deletions(-)

diff --git a/gix/src/revision/walk.rs b/gix/src/revision/walk.rs
index bdc233d9e41..9d62e474892 100644
--- a/gix/src/revision/walk.rs
+++ b/gix/src/revision/walk.rs
@@ -155,7 +155,7 @@ pub struct Platform<'repo> {
     /// The owning repository.
     pub repo: &'repo Repository,
     pub(crate) tips: Vec<ObjectId>,
-    pub(crate) prune: Vec<ObjectId>,
+    pub(crate) boundary: Vec<ObjectId>,
     pub(crate) sorting: Sorting,
     pub(crate) parents: gix_traverse::commit::Parents,
     pub(crate) use_commit_graph: Option<bool>,
@@ -171,7 +171,7 @@ impl<'repo> Platform<'repo> {
             parents: Default::default(),
             use_commit_graph: None,
             commit_graph: None,
-            prune: Vec::new(),
+            boundary: Vec::new(),
         }
     }
 }
@@ -210,15 +210,16 @@ impl Platform<'_> {
         self
     }
 
-    /// Prune the commit with the given `ids` such that they won't be returned, and such that none of their ancestors is returned either.
-    ///
-    /// Note that this forces the [sorting](Self::sorting) to
-    /// [`ByCommitTimeCutoff`](Sorting::ByCommitTimeCutoff) configured with
-    /// the oldest available commit time, ensuring that no commits older than the oldest of `ids` will be returned either.
+    /// Don't cross the given `ids` during traversal.
     ///
+    /// Note that this forces the [sorting](Self::sorting()) to [`ByCommitTimeCutoff`](Sorting::ByCommitTimeCutoff)
+    /// configured with the oldest available commit time, ensuring that no commits older than the oldest of `ids` will be returned either.
     /// Also note that commits that can't be accessed or are missing are simply ignored for the purpose of obtaining the cutoff date.
-    #[doc(alias = "hide", alias = "git2")]
-    pub fn with_pruned(mut self, ids: impl IntoIterator<Item = impl Into<ObjectId>>) -> Self {
+    ///
+    /// A boundary is distinctly different from exclusive refsepcs `^branch-to-not-list` in Git log.
+    ///
+    /// If this is not desired, [set the sorting](Self::sorting()) to something else right after this call.
+    pub fn with_boundary(mut self, ids: impl IntoIterator<Item = impl Into<ObjectId>>) -> Self {
         let (mut cutoff, order) = match self.sorting {
             Sorting::ByCommitTimeCutoff { seconds, order } => (Some(seconds), order),
             Sorting::ByCommitTime(order) => (None, order),
@@ -226,13 +227,13 @@ impl Platform<'_> {
         };
         for id in ids.into_iter() {
             let id = id.into();
-            if !self.prune.contains(&id) {
+            if !self.boundary.contains(&id) {
                 if let Some(time) = self.repo.find_commit(id).ok().and_then(|c| c.time().ok()) {
                     if cutoff.is_none() || cutoff > Some(time.seconds) {
                         cutoff = time.seconds.into();
                     }
                 }
-                self.prune.push(id);
+                self.boundary.push(id);
             }
         }
 
@@ -260,9 +261,9 @@ impl<'repo> Platform<'repo> {
             parents,
             use_commit_graph,
             commit_graph,
-            mut prune,
+            mut boundary,
         } = self;
-        prune.sort();
+        boundary.sort();
         Ok(revision::Walk {
             repo,
             inner: Box::new(
@@ -277,7 +278,7 @@ impl<'repo> Platform<'repo> {
                             return false;
                         }
                         let id = id.to_owned();
-                        if prune.binary_search(&id).is_ok() {
+                        if boundary.binary_search(&id).is_ok() {
                             return false;
                         }
                         match shallow_commits.as_ref() {
diff --git a/gix/tests/gix/id.rs b/gix/tests/gix/id.rs
index 2d2f24948fc..397d41c9cc1 100644
--- a/gix/tests/gix/id.rs
+++ b/gix/tests/gix/id.rs
@@ -140,7 +140,7 @@ mod ancestors {
         for use_commit_graph in [false, true] {
             let commits_graph_order = head
                 .ancestors()
-                .with_pruned(Some(hex_to_id("bcb05040a6925f2ff5e10d3ae1f9264f2e8c43ac")))
+                .with_boundary(Some(hex_to_id("bcb05040a6925f2ff5e10d3ae1f9264f2e8c43ac")))
                 .use_commit_graph(use_commit_graph)
                 .all()?
                 .map(|c| c.map(|c| c.id))