feat: Repository::merge_trees() now has a fully-wrapped outcome.

That way, more attached types are used for greater convenience.

Author: Byron

gix/src/lib.rs

@@ -120,8 +120,6 @@ pub use gix_ignore as ignore;
 #[cfg(feature = "index")]
 pub use gix_index as index;
 pub use gix_lock as lock;
-#[cfg(feature = "blob-merge")]
-pub use gix_merge as merge;
 #[cfg(feature = "credentials")]
 pub use gix_negotiate as negotiate;
 pub use gix_object as objs;
@@ -204,6 +202,9 @@ pub mod push;
 ///
 pub mod diff;
 
+///
+pub mod merge;
+
 /// See [`ThreadSafeRepository::discover()`], but returns a [`Repository`] instead.
 ///
 /// # Note

gix/src/merge.rs

@@ -0,0 +1,34 @@
+#[cfg(feature = "blob-merge")]
+pub use gix_merge as plumbing;
+
+///
+pub mod tree {
+    use gix_merge::tree::UnresolvedConflict;
+
+    /// The outcome produced by [`Repository::merge_trees()`](crate::Repository::merge_trees()).
+    #[derive(Clone)]
+    pub struct Outcome<'repo> {
+        /// The ready-made (but unwritten) *base* tree, including all non-conflicting changes, and the changes that had
+        /// conflicts which could be resolved automatically.
+        ///
+        /// This means, if all of their changes were conflicting, this will be equivalent to the *base* tree.
+        pub tree: crate::object::tree::Editor<'repo>,
+        /// The set of conflicts we encountered. Can be empty to indicate there was no conflict.
+        /// Note that conflicts might have been auto-resolved, but they are listed here for completeness.
+        /// Use [`has_unresolved_conflicts()`](Outcome::has_unresolved_conflicts()) to see if any action is needed
+        /// before using [`tree`](Outcome::tree).
+        pub conflicts: Vec<gix_merge::tree::Conflict>,
+        /// `true` if `conflicts` contains only a single *unresolved* conflict in the last slot, but possibly more resolved ones.
+        /// This also makes this outcome a very partial merge that cannot be completed.
+        /// Only set if [`fail_on_conflict`](Options::fail_on_conflict) is `true`.
+        pub failed_on_first_unresolved_conflict: bool,
+    }
+
+    impl Outcome<'_> {
+        /// Return `true` if there is any conflict that would still need to be resolved as they would yield undesirable trees.
+        /// This is based on `how` to determine what should be considered unresolved.
+        pub fn has_unresolved_conflicts(&self, how: UnresolvedConflict) -> bool {
+            self.conflicts.iter().any(|c| c.is_unresolved(how))
+        }
+    }
+}

gix/src/object/tree/mod.rs

@@ -6,10 +6,11 @@ use crate::{object::find, Id, ObjectDetached, Tree};
 
 /// All state needed to conveniently edit a tree, using only [update-or-insert](Editor::upsert()) and [removals](Editor::remove()).
 #[cfg(feature = "tree-editor")]
+#[derive(Clone)]
 pub struct Editor<'repo> {
-    inner: gix_object::tree::Editor<'repo>,
-    validate: gix_validate::path::component::Options,
-    repo: &'repo crate::Repository,
+    pub(crate) inner: gix_object::tree::Editor<'repo>,
+    pub(crate) validate: gix_validate::path::component::Options,
+    pub(crate) repo: &'repo crate::Repository,
 }
 
 /// Initialization

gix/src/repository/diff.rs

@@ -49,7 +49,7 @@ impl Repository {
         old_tree: impl Into<Option<&'a Tree<'old_repo>>>,
         new_tree: impl Into<Option<&'a Tree<'new_repo>>>,
         options: impl Into<Option<crate::diff::Options>>,
-    ) -> Result<Vec<gix_diff::tree_with_rewrites::Change>, diff_tree_to_tree::Error> {
+    ) -> Result<Vec<crate::object::tree::diff::ChangeDetached>, diff_tree_to_tree::Error> {
         let mut cache = self.diff_resource_cache(gix_diff::blob::pipeline::Mode::ToGit, Default::default())?;
         let opts = options
             .into()

gix/src/repository/merge.rs

@@ -124,10 +124,14 @@ impl Repository {
         their_tree: impl AsRef<gix_hash::oid>,
         labels: gix_merge::blob::builtin_driver::text::Labels<'_>,
         options: gix_merge::tree::Options,
-    ) -> Result<gix_merge::tree::Outcome<'_>, merge_trees::Error> {
+    ) -> Result<crate::merge::tree::Outcome<'_>, merge_trees::Error> {
         let mut diff_cache = self.diff_resource_cache_for_tree_diff()?;
         let mut blob_merge = self.merge_resource_cache(Default::default())?;
-        Ok(gix_merge::tree(
+        let gix_merge::tree::Outcome {
+            tree,
+            conflicts,
+            failed_on_first_unresolved_conflict,
+        } = gix_merge::tree(
             ancestor_tree.as_ref(),
             our_tree.as_ref(),
             their_tree.as_ref(),
@@ -138,6 +142,17 @@ impl Repository {
             &mut diff_cache,
             &mut blob_merge,
             options,
-        )?)
+        )?;
+
+        let validate = self.config.protect_options()?;
+        Ok(crate::merge::tree::Outcome {
+            tree: crate::object::tree::Editor {
+                inner: tree,
+                validate,
+                repo: self,
+            },
+            conflicts,
+            failed_on_first_unresolved_conflict,
+        })
     }
 }

gix/src/repository/mod.rs

@@ -125,6 +125,8 @@ pub mod merge_trees {
         DiffResourceCache(#[from] super::diff_resource_cache::Error),
         #[error(transparent)]
         TreeMerge(#[from] gix_merge::tree::Error),
+        #[error(transparent)]
+        ValidationOptions(#[from] crate::config::boolean::Error),
     }
 }