feat: add Repository::merge_base()

A simple method to obtain the merge-base between two commits.

Author: Byron

gix/Cargo.toml

@@ -118,7 +118,7 @@ attributes = [
 mailmap = ["dep:gix-mailmap", "revision"]
 
 ## Make revspec parsing possible, as well describing revision.
-revision = ["gix-revision/describe", "index"]
+revision = ["gix-revision/describe", "gix-revision/merge_base", "index"]
 
 ## If enabled, revspecs now support the regex syntax like `@^{/^.*x}`. Otherwise, only substring search is supported.
 ## This feature does increase compile time for niche-benefit, but is required for fully git-compatible revspec parsing.

gix/src/repository/mod.rs

@@ -72,6 +72,42 @@ mod submodule;
 mod thread_safe;
 mod worktree;
 
+///
+#[cfg(feature = "revision")]
+pub mod merge_base {
+    /// The error returned by [Repository::merge_base()](crate::Repository::merge_base()).
+    #[derive(Debug, thiserror::Error)]
+    #[allow(missing_docs)]
+    pub enum Error {
+        #[error(transparent)]
+        OpenCache(#[from] crate::repository::commit_graph_if_enabled::Error),
+        #[error(transparent)]
+        FindMergeBase(#[from] gix_revision::merge_base::Error),
+        #[error("Could not find a merge-base between commits {first} and {second}")]
+        NotFound {
+            first: gix_hash::ObjectId,
+            second: gix_hash::ObjectId,
+        },
+    }
+}
+
+///
+#[cfg(feature = "revision")]
+pub mod merge_base_with_cache {
+    /// The error returned by [Repository::merge_base_with_cache()](crate::Repository::merge_base_with_cache()).
+    #[derive(Debug, thiserror::Error)]
+    #[allow(missing_docs)]
+    pub enum Error {
+        #[error(transparent)]
+        FindMergeBase(#[from] gix_revision::merge_base::Error),
+        #[error("Could not find a merge-base between commits {first} and {second}")]
+        NotFound {
+            first: gix_hash::ObjectId,
+            second: gix_hash::ObjectId,
+        },
+    }
+}
+
 ///
 pub mod commit_graph_if_enabled {
     /// The error returned by [Repository::commit_graph_if_enabled()](crate::Repository::commit_graph_if_enabled()).

gix/src/repository/revision.rs

@@ -36,6 +36,78 @@ impl crate::Repository {
             .ok_or(revision::spec::parse::single::Error::RangedRev { spec: spec.into() })
     }
 
+    /// Obtain the best merge-base between commit `one` and `two`, or fail if there is none.
+    ///
+    /// # Performance
+    /// For repeated calls, prefer [`merge_base_with_cache()`](crate::Repository::merge_base_with_cache()).
+    /// Also be sure to [set an object cache](crate::Repository::object_cache_size_if_unset) to accelerate repeated commit lookups.
+    #[cfg(feature = "revision")]
+    pub fn merge_base(
+        &self,
+        one: impl Into<gix_hash::ObjectId>,
+        two: impl Into<gix_hash::ObjectId>,
+    ) -> Result<Id<'_>, super::merge_base::Error> {
+        use crate::prelude::ObjectIdExt;
+        let one = one.into();
+        let two = two.into();
+        let cache = self.commit_graph_if_enabled()?;
+        let mut graph = self.revision_graph(cache.as_ref());
+        let bases =
+            gix_revision::merge_base(one, &vec![two], &mut graph)?.ok_or(super::merge_base::Error::NotFound {
+                first: one,
+                second: two,
+            })?;
+        Ok(bases[0].attach(self))
+    }
+
+    /// Obtain the best merge-base between commit `one` and `two`, or fail if there is none, providing a
+    /// commit-graph `cache` to potentially greatly accelerate the operation.
+    ///
+    /// # Performance
+    /// Be sure to [set an object cache](crate::Repository::object_cache_size_if_unset) to accelerate repeated commit lookups.
+    #[cfg(feature = "revision")]
+    pub fn merge_base_with_cache(
+        &self,
+        one: impl Into<gix_hash::ObjectId>,
+        two: impl Into<gix_hash::ObjectId>,
+        cache: Option<&gix_commitgraph::Graph>,
+    ) -> Result<Id<'_>, super::merge_base_with_cache::Error> {
+        use crate::prelude::ObjectIdExt;
+        let one = one.into();
+        let two = two.into();
+        let mut graph = self.revision_graph(cache);
+        let bases = gix_revision::merge_base(one, &vec![two], &mut graph)?.ok_or(
+            super::merge_base_with_cache::Error::NotFound {
+                first: one,
+                second: two,
+            },
+        )?;
+        Ok(bases[0].attach(self))
+    }
+
+    /// Obtain all merge-bases between commit `one` and `others`, or an empty list if there is none, providing a
+    /// commit-graph `cache` to potentially greatly accelerate the operation.
+    ///
+    /// # Performance
+    /// Be sure to [set an object cache](crate::Repository::object_cache_size_if_unset) to accelerate repeated commit lookups.
+    #[doc(alias = "merge_bases_many", alias = "git2")]
+    #[cfg(feature = "revision")]
+    pub fn merge_bases_many_with_cache(
+        &self,
+        one: impl Into<gix_hash::ObjectId>,
+        others: &[gix_hash::ObjectId],
+        cache: Option<&gix_commitgraph::Graph>,
+    ) -> Result<Vec<Id<'_>>, gix_revision::merge_base::Error> {
+        use crate::prelude::ObjectIdExt;
+        let one = one.into();
+        let mut graph = self.revision_graph(cache);
+        Ok(gix_revision::merge_base(one, others, &mut graph)?
+            .unwrap_or_default()
+            .into_iter()
+            .map(|id| id.attach(self))
+            .collect())
+    }
+
     /// Create the baseline for a revision walk by initializing it with the `tips` to start iterating on.
     ///
     /// It can be configured further before starting the actual walk.