feat: add Repository::diff_tree_to_tree() for greater similarity to git2

Author: Byron

Cargo.lock

@@ -125,8 +125,9 @@ pub fn spawn_tree_delta_threads<'scope>(
                                 None => continue,
                             };
                             from.changes()?
-                                .track_filename()
-                                .track_rewrites(None)
+                                .options(|opts| {
+                                    opts.track_filename().track_rewrites(None);
+                                })
                                 .for_each_to_obtain_tree(&to, |change| {
                                     use gix::object::tree::diff::Change::*;
                                     changes.fetch_add(1, Ordering::Relaxed);

gitoxide-core/src/hours/core.rs

@@ -207,8 +207,9 @@ pub fn update(
                                         rewrite_cache.clear_resource_cache_keep_allocation();
                                         diff_cache.clear_resource_cache_keep_allocation();
                                         from.changes()?
-                                            .track_path()
-                                            .track_rewrites(Some(rewrites))
+                                            .options(|opts| {
+                                                opts.track_path().track_rewrites(Some(rewrites));
+                                            })
                                             .for_each_to_obtain_tree_with_cache(&to, &mut rewrite_cache, |change| {
                                                 use gix::object::tree::diff::Change::*;
                                                 change_counter.fetch_add(1, Ordering::SeqCst);

gitoxide-core/src/query/engine/update.rs

@@ -408,6 +408,7 @@ walkdir = "2.3.2"
 serial_test = { version = "3.1.0", default-features = false }
 async-std = { version = "1.12.0", features = ["attributes"] }
 termtree = "0.5.1"
+insta = "1.40.0"
 
 [package.metadata.docs.rs]
 features = [

gix/Cargo.toml

@@ -1,5 +1,109 @@
+use gix_diff::tree::recorder::Location;
 pub use gix_diff::*;
 
+///
+pub mod options {
+    ///
+    pub mod init {
+        /// The error returned when instantiating [diff options](crate::diff::Options).
+        #[derive(Debug, thiserror::Error)]
+        #[allow(missing_docs)]
+        pub enum Error {
+            #[cfg(feature = "blob-diff")]
+            #[error(transparent)]
+            RewritesConfiguration(#[from] crate::diff::new_rewrites::Error),
+        }
+    }
+}
+
+/// General diff-related options for configuring rename-tracking and blob diffs.
+#[derive(Debug, Copy, Clone)]
+pub struct Options {
+    location: Option<Location>,
+    #[cfg(feature = "blob-diff")]
+    rewrites: Option<gix_diff::Rewrites>,
+}
+
+impl Default for Options {
+    fn default() -> Self {
+        Options {
+            location: Some(Location::Path),
+            #[cfg(feature = "blob-diff")]
+            rewrites: None,
+        }
+    }
+}
+
+#[cfg(feature = "blob-diff")]
+impl From<Options> for gix_diff::tree_with_rewrites::Options {
+    fn from(opts: Options) -> Self {
+        gix_diff::tree_with_rewrites::Options {
+            location: opts.location,
+            #[cfg(feature = "blob-diff")]
+            rewrites: opts.rewrites,
+        }
+    }
+}
+
+/// Lifecycle
+impl Options {
+    #[cfg(feature = "blob-diff")]
+    pub(crate) fn from_configuration(config: &crate::config::Cache) -> Result<Self, options::init::Error> {
+        Ok(Options {
+            location: Some(Location::Path),
+            rewrites: config.diff_renames()?.unwrap_or_default().into(),
+        })
+    }
+}
+
+/// Setters
+impl Options {
+    /// Do not keep track of filepaths at all, which will leave all `location` fields empty.
+    pub fn no_locations(&mut self) -> &mut Self {
+        self.location = Some(Location::FileName);
+        self
+    }
+
+    /// Keep track of file-names, which makes `location` fields usable with the filename of the changed item.
+    pub fn track_filename(&mut self) -> &mut Self {
+        self.location = Some(Location::FileName);
+        self
+    }
+
+    /// Keep track of the entire path of a change, relative to the repository. (default).
+    ///
+    /// This makes the `location` field fully usable.
+    pub fn track_path(&mut self) -> &mut Self {
+        self.location = Some(Location::Path);
+        self
+    }
+
+    /// Provide `None` to disable rewrite tracking entirely, or pass `Some(<configuration>)` to control to
+    /// what extent rename and copy tracking is performed.
+    ///
+    /// Note that by default, the git configuration determines rewrite tracking and git defaults are used
+    /// if nothing is configured, which turns rename tracking with 50% similarity on, while not tracking copies at all.
+    #[cfg(feature = "blob-diff")]
+    pub fn track_rewrites(&mut self, renames: Option<gix_diff::Rewrites>) -> &mut Self {
+        self.rewrites = renames;
+        self
+    }
+}
+
+/// Builder
+impl Options {
+    /// Provide `None` to disable rewrite tracking entirely, or pass `Some(<configuration>)` to control to
+    /// what extent rename and copy tracking is performed.
+    ///
+    /// Note that by default, the git configuration determines rewrite tracking and git defaults are used
+    /// if nothing is configured, which turns rename tracking with 50% similarity on, while not tracking copies at all.
+    #[cfg(feature = "blob-diff")]
+    pub fn with_rewrites(mut self, renames: Option<gix_diff::Rewrites>) -> Self {
+        self.rewrites = renames;
+        self
+    }
+}
+
 ///
 pub mod rename {
     /// Determine how to do rename tracking.

gix/src/diff.rs

@@ -74,6 +74,7 @@ impl<'old> Platform<'_, 'old> {
             }
             Some(cache) => cache,
         };
+        let opts = self.options.into();
         Ok(gix_diff::tree_with_rewrites(
             TreeRefIter::from_bytes(&self.lhs.data),
             TreeRefIter::from_bytes(&other.data),
@@ -86,10 +87,7 @@ impl<'old> Platform<'_, 'old> {
                     Action::Cancel => gix_diff::tree_with_rewrites::Action::Cancel,
                 })
             },
-            gix_diff::tree_with_rewrites::Options {
-                location: self.location,
-                rewrites: self.rewrites,
-            },
+            opts,
         )?)
     }
 }

gix/src/object/tree/diff/for_each.rs

@@ -1,7 +1,6 @@
 use gix_diff::tree;
-use gix_diff::tree::recorder::Location;
 
-use crate::{bstr::BStr, diff::Rewrites, Id, Tree};
+use crate::{bstr::BStr, Id, Tree};
 
 /// Returned by the `for_each` function to control flow.
 #[derive(Default, Clone, Copy, PartialOrd, PartialEq, Ord, Eq, Hash)]
@@ -18,9 +17,9 @@ pub enum Action {
 pub enum Change<'a, 'old, 'new> {
     /// An entry was added, like the addition of a file or directory.
     Addition {
-        /// The location of the file or directory, if [tracking](Platform::track_path) was enabled.
+        /// The location of the file or directory, if [tracking](crate::diff::Options::track_path) was enabled.
         ///
-        /// It may be empty if neither [file names](Platform::track_filename()) nor [file paths](Platform::track_path())
+        /// It may be empty if neither [file names](crate::diff::Options::track_filename()) nor [file paths](crate::diff::Options::track_path())
         /// are tracked.
         location: &'a BStr,
         /// The mode of the added entry.
@@ -33,7 +32,7 @@ pub enum Change<'a, 'old, 'new> {
     },
     /// An entry was deleted, like the deletion of a file or directory.
     Deletion {
-        /// The location of the file or directory, if [tracking](Platform::track_path) was enabled.
+        /// The location of the file or directory, if [tracking](crate::diff::Options::track_path) was enabled.
         ///
         /// Otherwise, this value is always an empty path.
         location: &'a BStr,
@@ -48,9 +47,9 @@ pub enum Change<'a, 'old, 'new> {
     /// An entry was modified, e.g. changing the contents of a file adjusts its object id and turning
     /// a file into a symbolic link adjusts its mode.
     Modification {
-        /// The location of the file or directory, if [tracking](Platform::track_path) was enabled.
+        /// The location of the file or directory, if [tracking](crate::diff::Options::track_path) was enabled.
         ///
-        /// It may be empty if neither [file names](Platform::track_filename()) nor [file paths](Platform::track_path())
+        /// It may be empty if neither [file names](crate::diff::Options::track_filename()) nor [file paths](crate::diff::Options::track_path())
         /// are tracked.
         location: &'a BStr,
         /// The mode of the entry before the modification.
@@ -70,13 +69,13 @@ pub enum Change<'a, 'old, 'new> {
     ///
     /// In case of copies, the `copy` flag is true and typically represents a perfect copy of a source was made.
     ///
-    /// This variant can only be encountered if [rewrite tracking](Platform::track_rewrites()) is enabled.
+    /// This variant can only be encountered if [rewrite tracking](crate::diff::Options::track_rewrites()) is enabled.
     ///
     /// Note that mode changes may have occurred as well, i.e. changes from executable to non-executable or vice-versa.
     Rewrite {
         /// The location of the source of the rename operation.
         ///
-        /// It may be empty if neither [file names](Platform::track_filename()) nor [file paths](Platform::track_path())
+        /// It may be empty if neither [file names](crate::diff::Options::track_filename()) nor [file paths](crate::diff::Options::track_path())
         /// are tracked.
         source_location: &'a BStr,
         /// Identifies a relationship between the source and another source,
@@ -86,7 +85,7 @@ pub enum Change<'a, 'old, 'new> {
         source_entry_mode: gix_object::tree::EntryMode,
         /// The object id of the entry before the rename.
         ///
-        /// Note that this is the same as `id` if we require the [similarity to be 100%](Rewrites::percentage), but may
+        /// Note that this is the same as `id` if we require the [similarity to be 100%](gix_diff::Rewrites::percentage), but may
         /// be different otherwise.
         source_id: Id<'old>,
         /// Information about the diff we performed to detect similarity and match the `source_id` with the current state at `id`.
@@ -95,9 +94,9 @@ pub enum Change<'a, 'old, 'new> {
         /// The mode of the entry after the rename.
         /// It could differ but still be considered a rename as we are concerned only about content.
         entry_mode: gix_object::tree::EntryMode,
-        /// The location of the destination file or directory, if [tracking](Platform::track_path) was enabled.
+        /// The location of the destination file or directory, if [tracking](crate::diff::Options::track_path) was enabled.
         ///
-        /// It may be empty if neither [file names](Platform::track_filename()) nor [file paths](Platform::track_path())
+        /// It may be empty if neither [file names](crate::diff::Options::track_filename()) nor [file paths](crate::diff::Options::track_path())
         /// are tracked.
         location: &'a BStr,
         /// The object id after the rename.
@@ -126,15 +125,14 @@ impl<'repo> Tree<'repo> {
     ///
     /// Note that if a clone with `--filter=blob=none` was created, rename tracking may fail as it might
     /// try to access blobs to compute a similarity metric. Thus, it's more compatible to turn rewrite tracking off
-    /// using [`Platform::track_rewrites()`].
+    /// using [`Options::track_rewrites()`](crate::diff::Options::track_rewrites()).
     #[allow(clippy::result_large_err)]
     #[doc(alias = "diff_tree_to_tree", alias = "git2")]
-    pub fn changes<'a>(&'a self) -> Result<Platform<'a, 'repo>, crate::diff::new_rewrites::Error> {
+    pub fn changes<'a>(&'a self) -> Result<Platform<'a, 'repo>, crate::diff::options::init::Error> {
         Ok(Platform {
             state: Default::default(),
             lhs: self,
-            location: Some(Location::Path),
-            rewrites: self.repo.config.diff_renames()?.unwrap_or_default().into(),
+            options: crate::diff::Options::from_configuration(&self.repo.config)?,
         })
     }
 }
@@ -144,39 +142,13 @@ impl<'repo> Tree<'repo> {
 pub struct Platform<'a, 'repo> {
     state: gix_diff::tree::State,
     lhs: &'a Tree<'repo>,
-    location: Option<Location>,
-    rewrites: Option<Rewrites>,
+    options: crate::diff::Options,
 }
 
-/// Configuration
 impl Platform<'_, '_> {
-    /// Do not keep track of filepaths at all, which will leave all [`location`][Change::location] fields empty.
-    pub fn no_locations(&mut self) -> &mut Self {
-        self.location = Some(Location::FileName);
-        self
-    }
-
-    /// Keep track of file-names, which makes the [`location`][Change::location] field usable with the filename of the changed item.
-    pub fn track_filename(&mut self) -> &mut Self {
-        self.location = Some(Location::FileName);
-        self
-    }
-
-    /// Keep track of the entire path of a change, relative to the repository. (default).
-    ///
-    /// This makes the [`location`][Change::location] field usable.
-    pub fn track_path(&mut self) -> &mut Self {
-        self.location = Some(Location::Path);
-        self
-    }
-
-    /// Provide `None` to disable rewrite tracking entirely, or pass `Some(<configuration>)` to control to
-    /// what extent rename and copy tracking is performed.
-    ///
-    /// Note that by default, the git configuration determines rewrite tracking and git defaults are used
-    /// if nothing is configured, which turns rename tracking with 50% similarity on, while not tracking copies at all.
-    pub fn track_rewrites(&mut self, renames: Option<Rewrites>) -> &mut Self {
-        self.rewrites = renames;
+    /// Adjust diff options with `change_opts`.
+    pub fn options(&mut self, change_opts: impl FnOnce(&mut crate::diff::Options)) -> &mut Self {
+        change_opts(&mut self.options);
         self
     }
 }
@@ -214,7 +186,7 @@ impl Platform<'_, '_> {
     ///
     /// ### Performance Notes
     ///
-    /// Be sure to forcefully disable [`track_rewrites(None)`](Self::track_rewrites) to avoid
+    /// Be sure to forcefully disable [`track_rewrites(None)`](crate::diff::Options::track_rewrites) to avoid
     /// rename tracking, an operation that doesn't affect the statistics currently.
     /// As diffed resources aren't cached, if highly repetitive blobs are expected, performance
     /// may be diminished. In real-world scenarios where blobs are mostly unique, that's not an issue though.

gix/src/object/tree/diff/mod.rs

@@ -1,5 +1,6 @@
-use crate::repository::diff_resource_cache;
-use crate::Repository;
+use crate::repository::{diff_resource_cache, diff_tree_to_tree};
+use crate::{Repository, Tree};
+use gix_object::TreeRefIter;
 
 /// Diff-utilities
 impl Repository {
@@ -35,6 +36,45 @@ impl Repository {
         )?)
     }
 
+    /// Produce the changes that would need to be applied to `old_tree` to create `new_tree`.
+    /// If `options` are unset, they will be filled in according to the git configuration of this repository, and with
+    /// [full paths being tracked](crate::diff::Options::track_path()) as well, which typically means that
+    /// rewrite tracking might be disabled if done so explicitly by the user.
+    /// If `options` are set, the user can take full control over the settings.
+    ///
+    /// Note that this method exists to evoke similarity to `git2`, and makes it easier to fully control diff settings.
+    /// A more fluent version [may be used as well](Tree::changes()).
+    pub fn diff_tree_to_tree<'a, 'old_repo: 'a, 'new_repo: 'a>(
+        &self,
+        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> {
+        let mut cache = self.diff_resource_cache(gix_diff::blob::pipeline::Mode::ToGit, Default::default())?;
+        let opts = options
+            .into()
+            .map_or_else(|| crate::diff::Options::from_configuration(&self.config), Ok)?
+            .into();
+
+        let empty_tree = self.empty_tree();
+        let old_tree = old_tree.into().unwrap_or(&empty_tree);
+        let new_tree = new_tree.into().unwrap_or(&empty_tree);
+        let mut out = Vec::new();
+        gix_diff::tree_with_rewrites(
+            TreeRefIter::from_bytes(&old_tree.data),
+            TreeRefIter::from_bytes(&new_tree.data),
+            &mut cache,
+            &mut Default::default(),
+            &self.objects,
+            |change| -> Result<_, std::convert::Infallible> {
+                out.push(change.into_owned());
+                Ok(gix_diff::tree_with_rewrites::Action::Continue)
+            },
+            opts,
+        )?;
+        Ok(out)
+    }
+
     /// Return a resource cache suitable for diffing blobs from trees directly, where no worktree checkout exists.
     ///
     /// For more control, see [`diff_resource_cache()`](Self::diff_resource_cache).

gix/src/repository/diff.rs

@@ -58,6 +58,22 @@ mod submodule;
 mod thread_safe;
 mod worktree;
 
+///
+#[cfg(feature = "blob-diff")]
+pub mod diff_tree_to_tree {
+    /// The error returned by [Repository::diff_tree_to_tree()](crate::Repository::diff_tree_to_tree()).
+    #[derive(Debug, thiserror::Error)]
+    #[allow(missing_docs)]
+    pub enum Error {
+        #[error(transparent)]
+        DiffOptions(#[from] crate::diff::options::init::Error),
+        #[error(transparent)]
+        CreateResourceCache(#[from] super::diff_resource_cache::Error),
+        #[error(transparent)]
+        TreeDiff(#[from] gix_diff::tree_with_rewrites::Error),
+    }
+}
+
 ///
 #[cfg(feature = "blob-merge")]
 pub mod blob_merge_options {