feat: add Repository::merge_commits()

It's often more convenient to work with commits when merging, especially
when merge-bases are dealt with automatically.

Author: Byron

gix/src/merge.rs

@@ -2,6 +2,90 @@ pub use gix_merge as plumbing;
 
 pub use gix_merge::blob;
 
+///
+pub mod commit {
+    /// The outcome produced by [`Repository::merge_commits()`](crate::Repository::merge_commits()).
+    #[derive(Clone)]
+    pub struct Outcome<'a> {
+        /// The outcome of the actual tree-merge, with the tree editor to write to obtain the actual tree id.
+        pub tree_merge: crate::merge::tree::Outcome<'a>,
+        /// The tree id of the base commit we used. This is either…
+        /// * the single merge-base we found
+        /// * the first of multiple merge-bases if [Options::with_use_first_merge_base()] was `true`.
+        /// * the merged tree of all merge-bases, which then isn't linked to an actual commit.
+        /// * an empty tree, if [Options::with_allow_missing_merge_base()] is enabled.
+        pub merge_base_tree_id: gix_hash::ObjectId,
+        /// The object ids of all the commits which were found to be merge-bases, or `None` if there was no merge-base.
+        pub merge_bases: Option<Vec<gix_hash::ObjectId>>,
+        /// A list of virtual commits that were created to merge multiple merge-bases into one, the last one being
+        /// the one we used as merge-base for the merge.
+        /// As they are not reachable by anything they will be garbage collected, but knowing them provides options.
+        /// Would be empty if no virtual commit was needed at all as there was only a single merge-base.
+        /// Otherwise, the last commit id is the one with the `merge_base_tree_id`.
+        pub virtual_merge_bases: Vec<gix_hash::ObjectId>,
+    }
+
+    /// A way to configure [`Repository::merge_commits()`](crate::Repository::merge_commits()).
+    #[derive(Default, Debug, Clone)]
+    pub struct Options {
+        allow_missing_merge_base: bool,
+        tree_merge: crate::merge::tree::Options,
+        use_first_merge_base: bool,
+    }
+
+    impl From<gix_merge::tree::Options> for Options {
+        fn from(value: gix_merge::tree::Options) -> Self {
+            Options {
+                tree_merge: value.into(),
+                use_first_merge_base: false,
+                allow_missing_merge_base: false,
+            }
+        }
+    }
+
+    impl From<crate::merge::tree::Options> for Options {
+        fn from(value: crate::merge::tree::Options) -> Self {
+            Options {
+                tree_merge: value,
+                use_first_merge_base: false,
+                allow_missing_merge_base: false,
+            }
+        }
+    }
+
+    impl From<Options> for gix_merge::commit::Options {
+        fn from(
+            Options {
+                allow_missing_merge_base,
+                tree_merge,
+                use_first_merge_base,
+            }: Options,
+        ) -> Self {
+            gix_merge::commit::Options {
+                allow_missing_merge_base,
+                tree_merge: tree_merge.into(),
+                use_first_merge_base,
+            }
+        }
+    }
+
+    /// Builder
+    impl Options {
+        /// If `true`, merging unrelated commits is allowed, with the merge-base being assumed as empty tree.
+        pub fn with_allow_missing_merge_base(mut self, allow_missing_merge_base: bool) -> Self {
+            self.allow_missing_merge_base = allow_missing_merge_base;
+            self
+        }
+
+        /// If `true`, do not merge multiple merge-bases into one. Instead, just use the first one.
+        #[doc(alias = "no_recursive", alias = "git2")]
+        pub fn with_use_first_merge_base(mut self, use_first_merge_base: bool) -> Self {
+            self.use_first_merge_base = use_first_merge_base;
+            self
+        }
+    }
+}
+
 ///
 pub mod tree {
     use gix_merge::blob::builtin_driver;

gix/src/repository/merge.rs

@@ -1,6 +1,7 @@
 use crate::config::cache::util::ApplyLeniencyDefault;
 use crate::config::tree;
-use crate::repository::{blob_merge_options, merge_resource_cache, merge_trees, tree_merge_options};
+use crate::prelude::ObjectIdExt;
+use crate::repository::{blob_merge_options, merge_commits, merge_resource_cache, merge_trees, tree_merge_options};
 use crate::Repository;
 use gix_merge::blob::builtin_driver::text;
 use gix_object::Write;
@@ -102,7 +103,7 @@ impl Repository {
     }
 
     /// Merge `our_tree` and `their_tree` together, assuming they have the same `ancestor_tree`, to yield a new tree
-    /// which is provided as [tree editor](gix_object::tree::Editor) to inspect and finalize results at will.
+    /// which is provided as [tree editor](crate::object::tree::Editor) to inspect and finalize results at will.
     /// No change to the worktree or index is made, but objects may be written to the object database as merge results
     /// are stored.
     /// If these changes should not be observable outside of this instance, consider [enabling object memory](Self::with_object_memory).
@@ -115,7 +116,7 @@ impl Repository {
     ///
     /// ### Performance
     ///
-    /// It's highly recommended to [set an object cache](crate::Repository::compute_object_cache_size_for_tree_diffs)
+    /// It's highly recommended to [set an object cache](Repository::compute_object_cache_size_for_tree_diffs)
     /// to avoid extracting the same object multiple times.
     pub fn merge_trees(
         &self,
@@ -155,4 +156,71 @@ impl Repository {
             failed_on_first_unresolved_conflict,
         })
     }
+
+    /// Merge `our_commit` and `their_commit` together to yield a new tree which is provided as [tree editor](crate::object::tree::Editor)
+    /// to inspect and finalize results at will. The merge-base will be determined automatically between both commits, along with special
+    /// handling in case there are multiple merge-bases.
+    /// No change to the worktree or index is made, but objects may be written to the object database as merge results
+    /// are stored.
+    /// If these changes should not be observable outside of this instance, consider [enabling object memory](Self::with_object_memory).
+    ///
+    /// `labels` are typically chosen to identify the refs or names for `our_commit` and `their_commit`, with the ancestor being set
+    /// automatically as part of the merge-base handling.
+    ///
+    /// `options` should be initialized with [`Repository::tree_merge_options().into()`](Self::tree_merge_options()).
+    ///
+    /// ### Performance
+    ///
+    /// It's highly recommended to [set an object cache](Repository::compute_object_cache_size_for_tree_diffs)
+    /// to avoid extracting the same object multiple times.
+    pub fn merge_commits(
+        &self,
+        our_commit: impl Into<gix_hash::ObjectId>,
+        their_commit: impl Into<gix_hash::ObjectId>,
+        labels: gix_merge::blob::builtin_driver::text::Labels<'_>,
+        options: crate::merge::commit::Options,
+    ) -> Result<crate::merge::commit::Outcome<'_>, merge_commits::Error> {
+        let mut diff_cache = self.diff_resource_cache_for_tree_diff()?;
+        let mut blob_merge = self.merge_resource_cache(Default::default())?;
+        let commit_graph = self.commit_graph_if_enabled()?;
+        let mut graph = self.revision_graph(commit_graph.as_ref());
+        let gix_merge::commit::Outcome {
+            tree_merge:
+                gix_merge::tree::Outcome {
+                    tree,
+                    conflicts,
+                    failed_on_first_unresolved_conflict,
+                },
+            merge_base_tree_id,
+            merge_bases,
+            virtual_merge_bases,
+        } = gix_merge::commit(
+            our_commit.into(),
+            their_commit.into(),
+            labels,
+            &mut graph,
+            &mut diff_cache,
+            &mut blob_merge,
+            self,
+            &mut |id| id.to_owned().attach(self).shorten_or_id().to_string(),
+            options.into(),
+        )?;
+
+        let validate = self.config.protect_options()?;
+        let tree_merge = crate::merge::tree::Outcome {
+            tree: crate::object::tree::Editor {
+                inner: tree,
+                validate,
+                repo: self,
+            },
+            conflicts,
+            failed_on_first_unresolved_conflict,
+        };
+        Ok(crate::merge::commit::Outcome {
+            tree_merge,
+            merge_base_tree_id,
+            merge_bases,
+            virtual_merge_bases,
+        })
+    }
 }

gix/src/repository/mod.rs

@@ -130,6 +130,26 @@ pub mod merge_trees {
     }
 }
 
+///
+#[cfg(feature = "merge")]
+pub mod merge_commits {
+    /// The error returned by [Repository::merge_commits()](crate::Repository::merge_commits()).
+    #[derive(Debug, thiserror::Error)]
+    #[allow(missing_docs)]
+    pub enum Error {
+        #[error(transparent)]
+        OpenCommitGraph(#[from] super::commit_graph_if_enabled::Error),
+        #[error(transparent)]
+        MergeResourceCache(#[from] super::merge_resource_cache::Error),
+        #[error(transparent)]
+        DiffResourceCache(#[from] super::diff_resource_cache::Error),
+        #[error(transparent)]
+        CommitMerge(#[from] gix_merge::commit::Error),
+        #[error(transparent)]
+        ValidationOptions(#[from] crate::config::boolean::Error),
+    }
+}
+
 ///
 #[cfg(feature = "merge")]
 pub mod tree_merge_options {