feat!: better handling and tracking of directory renames

Deletations that are caused by deletions higher up will now carry
IDs to associate them with each other. This allows to bundle them
at a later stage to re-obtain directory deletions.

Author: Byron

gix-diff/src/tree/changes.rs

@@ -1,23 +1,43 @@
-use std::collections::VecDeque;
-
+use crate::tree::visit::Relation;
+use bstr::BStr;
 use gix_hash::ObjectId;
 use gix_object::{bstr::BString, TreeRefIter};
+use std::collections::VecDeque;
+
+/// A trait to allow responding to a traversal designed to figure out the [changes](visit::Change)
+/// to turn tree A into tree B.
+pub trait Visit {
+    /// Sets the full path in front of the queue so future calls to push and pop components affect it instead.
+    fn pop_front_tracked_path_and_set_current(&mut self);
+    /// Append a `component` to the end of a path, which may be empty.
+    fn push_back_tracked_path_component(&mut self, component: &BStr);
+    /// Append a `component` to the end of a path, which may be empty.
+    fn push_path_component(&mut self, component: &BStr);
+    /// Removes the last component from the path, which may leave it empty.
+    fn pop_path_component(&mut self);
+    /// Record a `change` and return an instruction whether to continue or not.
+    ///
+    /// The implementation may use the current path to lean where in the tree the change is located.
+    fn visit(&mut self, change: visit::Change) -> visit::Action;
+}
 
 /// The state required to visit [Changes] to be instantiated with `State::default()`.
 #[derive(Default, Clone)]
 pub struct State {
     buf1: Vec<u8>,
     buf2: Vec<u8>,
-    trees: VecDeque<TreeInfoPair>,
+    trees: VecDeque<TreeInfoTuple>,
+    change_id: visit::ChangeId,
 }
 
-type TreeInfoPair = (Option<ObjectId>, Option<ObjectId>);
+type TreeInfoTuple = (Option<ObjectId>, Option<ObjectId>, Option<Relation>);
 
 impl State {
     fn clear(&mut self) {
         self.trees.clear();
         self.buf1.clear();
         self.buf2.clear();
+        self.change_id = 0;
     }
 }
 
@@ -38,8 +58,6 @@ pub mod changes;
 
 ///
 pub mod visit;
-#[doc(inline)]
-pub use visit::Visit;
 
 /// A [Visit] implementation to record every observed change and keep track of the changed paths.
 #[derive(Clone, Debug)]

gix-diff/src/tree/mod.rs

@@ -4,7 +4,8 @@ use gix_object::{
     tree,
 };
 
-use crate::tree::{visit, Recorder};
+use crate::tree::visit::Relation;
+use crate::tree::{visit, Recorder, Visit};
 
 /// Describe how to track the location of a change.
 #[derive(Debug, Clone, Copy, Eq, PartialEq)]
@@ -17,7 +18,7 @@ pub enum Location {
     FileName,
 }
 
-/// A Change as observed by a call to [`visit(…)`][visit::Visit::visit()], enhanced with the path affected by the change.
+/// A Change as observed by a call to [`visit(…)`](Visit::visit()), enhanced with the path affected by the change.
 /// Its similar to [`visit::Change`] but includes the path that changed.
 #[derive(Clone, Debug, PartialEq, Eq)]
 #[allow(missing_docs)]
@@ -26,11 +27,13 @@ pub enum Change {
         entry_mode: tree::EntryMode,
         oid: ObjectId,
         path: BString,
+        relation: Option<Relation>,
     },
     Deletion {
         entry_mode: tree::EntryMode,
         oid: ObjectId,
         path: BString,
+        relation: Option<Relation>,
     },
     Modification {
         previous_entry_mode: tree::EntryMode,
@@ -93,7 +96,7 @@ impl Recorder {
     }
 }
 
-impl visit::Visit for Recorder {
+impl Visit for Recorder {
     fn pop_front_tracked_path_and_set_current(&mut self) {
         if let Some(Location::Path) = self.location {
             self.path = self.path_deque.pop_front().expect("every parent is set only once");
@@ -136,15 +139,25 @@ impl visit::Visit for Recorder {
     fn visit(&mut self, change: visit::Change) -> visit::Action {
         use visit::Change::*;
         self.records.push(match change {
-            Deletion { entry_mode, oid } => Change::Deletion {
+            Deletion {
+                entry_mode,
+                oid,
+                relation,
+            } => Change::Deletion {
                 entry_mode,
                 oid,
                 path: self.path_clone(),
+                relation,
             },
-            Addition { entry_mode, oid } => Change::Addition {
+            Addition {
+                entry_mode,
+                oid,
+                relation,
+            } => Change::Addition {
                 entry_mode,
                 oid,
                 path: self.path_clone(),
+                relation,
             },
             Modification {
                 previous_entry_mode,

gix-diff/src/tree/recorder.rs

@@ -1,5 +1,23 @@
 use gix_hash::ObjectId;
-use gix_object::{bstr::BStr, tree, tree::EntryMode};
+use gix_object::{tree, tree::EntryMode};
+
+/// A way to recognize and associate different [`Change`] instances.
+///
+/// These are unique only within one diff operation.
+pub type ChangeId = u32;
+
+/// Identifies a relationship between this instance and another one.
+#[derive(Debug, Copy, Clone, PartialOrd, PartialEq, Ord, Eq, Hash)]
+pub enum Relation {
+    /// This is a parent with the given ID, which will always have at least one child
+    /// assuming that empty directories are not allowed in valid trees.
+    /// It's also always a tree which is the start of a recursive deletion or addition.
+    ///
+    /// The change with this relation is always emitted first.
+    Parent(ChangeId),
+    /// This is a direct or indirect child, tree or not tree, of the parent with the given ID.
+    ChildOfParent(ChangeId),
+}
 
 /// Represents any possible change in order to turn one tree into another.
 #[derive(Debug, Clone, PartialOrd, PartialEq, Ord, Eq, Hash)]
@@ -10,13 +28,17 @@ pub enum Change {
         entry_mode: tree::EntryMode,
         /// The object id of the added entry.
         oid: ObjectId,
+        /// Possibly associate this change with another for hierarchical rename tracking.
+        relation: Option<Relation>,
     },
     /// An entry was deleted, like the deletion of a file or directory.
     Deletion {
         /// The mode of the deleted entry.
         entry_mode: tree::EntryMode,
         /// The object id of the deleted entry.
         oid: ObjectId,
+        /// Possibly associate this change with another for hierarchical rename tracking.
+        relation: Option<Relation>,
     },
     /// 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.
@@ -51,20 +73,28 @@ impl Change {
     /// Return the current object id and tree entry mode of a change.
     pub fn oid_and_entry_mode(&self) -> (&gix_hash::oid, EntryMode) {
         match self {
-            Change::Addition { oid, entry_mode }
-            | Change::Deletion { oid, entry_mode }
+            Change::Addition {
+                oid,
+                entry_mode,
+                relation: _,
+            }
+            | Change::Deletion {
+                oid,
+                entry_mode,
+                relation: _,
+            }
             | Change::Modification { oid, entry_mode, .. } => (oid, *entry_mode),
         }
     }
 }
 
-/// What to do after a [Change] was [recorded][Visit::visit()].
+/// What to do after a [Change] was [recorded](super::Visit::visit()).
 #[derive(Default, Clone, Copy, PartialOrd, PartialEq, Ord, Eq, Hash)]
 pub enum Action {
     /// Continue the traversal of changes.
     #[default]
     Continue,
-    /// Stop the traversal of changes, making this the last call to [visit(…)][Visit::visit()].
+    /// Stop the traversal of changes, making this the last call to [visit(…)](super::Visit::visit()).
     Cancel,
 }
 
@@ -75,23 +105,6 @@ impl Action {
     }
 }
 
-/// A trait to allow responding to a traversal designed to figure out the [changes][Change]
-/// to turn tree A into tree B.
-pub trait Visit {
-    /// Sets the full path path in front of the queue so future calls to push and pop components affect it instead.
-    fn pop_front_tracked_path_and_set_current(&mut self);
-    /// Append a `component` to the end of a path, which may be empty.
-    fn push_back_tracked_path_component(&mut self, component: &BStr);
-    /// Append a `component` to the end of a path, which may be empty.
-    fn push_path_component(&mut self, component: &BStr);
-    /// Removes the last component from the path, which may leave it empty.
-    fn pop_path_component(&mut self);
-    /// Record a `change` and return an instruction whether to continue or not.
-    ///
-    /// The implementation may use the current path to lean where in the tree the change is located.
-    fn visit(&mut self, change: Change) -> Action;
-}
-
 #[cfg(feature = "blob")]
 mod change_impls {
     use gix_hash::oid;
@@ -140,8 +153,8 @@ mod tests {
     fn size_of_change() {
         let actual = std::mem::size_of::<Change>();
         assert!(
-            actual <= 46,
-            "{actual} <= 46: this type shouldn't grow without us knowing"
+            actual <= 48,
+            "{actual} <= 48: this type shouldn't grow without us knowing"
         );
     }
 }

gix-diff/src/tree/visit.rs

@@ -99,6 +99,9 @@ git commit -qam 'rm g/aa, add g/a'
 rm -Rf ./* && mkdir git-sec gix && touch a git-sec/2 git-sequencer h gix/5 && git add .
 git commit -am "clear slate"
 
-git mv git-sec gix-sec && git commit -m "interesting rename 1"
+mkdir git-sec/subdir && touch git-sec/subdir/6 git-sec/7
+git add . && git commit -m "add files to git-sec"
 
-git mv gix-sec git-sec && git commit -m "interesting rename 2"
+git mv git-sec gix-sec && git commit -m "rename git-sec to gix-sec"
+
+git mv gix-sec git-sec && git commit -m "rename gix-sec to git-sec"