feat: provide a way to record and apply index changes.

These changes will then be applicable to an index that is created
from the written tree editor.

Author: Byron

Cargo.lock

@@ -32,6 +32,7 @@ gix-quote = { version = "^0.4.13", path = "../gix-quote" }
 gix-revision = { version = "^0.30.0", path = "../gix-revision", default-features = false, features = ["merge_base"] }
 gix-revwalk = { version = "^0.16.0", path = "../gix-revwalk" }
 gix-diff = { version = "^0.47.0", path = "../gix-diff", default-features = false, features = ["blob"] }
+gix-index = { version = "^0.36.0", path = "../gix-index" }
 
 thiserror = "2.0.0"
 imara-diff = { version = "0.1.7" }

gix-merge/Cargo.toml

@@ -81,6 +81,17 @@ impl Outcome<'_> {
     pub fn has_unresolved_conflicts(&self, how: TreatAsUnresolved) -> bool {
         self.conflicts.iter().any(|c| c.is_unresolved(how))
     }
+
+    /// Returns `true` if `index` changed as we applied conflicting stages to it.
+    /// It's important that `index` is at the state of [`Self::tree`].
+    ///
+    /// Note that in practice, whenever there is a single [conflict], this function will return `true`.
+    pub fn index_changed_after_applying_conflicts(
+        &self,
+        index: &mut gix_index::State,
+    ) -> Result<bool, apply_index_entries::Error> {
+        apply_index_entries(&self.conflicts, index)
+    }
 }
 
 /// A description of a conflict (i.e. merge issue without an auto-resolution) as seen during a [tree-merge](crate::tree()).
@@ -99,11 +110,25 @@ pub struct Conflict {
     pub ours: Change,
     /// The change representing *their* side.
     pub theirs: Change,
+    /// An array to store an entry for each stage of the conflict.
+    /// Note that ours and theirs might be swapped, so one should access it through [`Self::entries()`].
+    pub entries: [Option<ConflictIndexEntry>; 3],
     /// Determine how to interpret the `ours` and `theirs` fields. This is used to implement [`Self::changes_in_resolution()`]
     /// and [`Self::into_parts_by_resolution()`].
     map: ConflictMapping,
 }
 
+/// A conflicting entry for insertion into the index.
+/// It will always be either on stage 1 (ancestor/base), 2 (ours) or 3 (theirs)
+#[derive(Debug, Clone, Copy)]
+pub struct ConflictIndexEntry {
+    /// The kind of object at this stage.
+    /// Note that it's possible that this is a directory, for instance if a directory was replaced with a file.
+    pub mode: gix_object::tree::EntryMode,
+    /// The id defining the state of the object.
+    pub id: gix_hash::ObjectId,
+}
+
 /// A utility to help define which side is what in the [`Conflict`] type.
 #[derive(Debug, Clone, Copy)]
 enum ConflictMapping {
@@ -178,6 +203,14 @@ impl Conflict {
         }
     }
 
+    /// Return the index entries for insertion into the index, to match with what's returned by [`Self::changes_in_resolution()`].
+    pub fn entries(&self) -> [Option<ConflictIndexEntry>; 3] {
+        match self.map {
+            ConflictMapping::Original => self.entries,
+            ConflictMapping::Swapped => [self.entries[0], self.entries[2], self.entries[1]],
+        }
+    }
+
     /// Return information about the content merge if it was performed.
     pub fn content_merge(&self) -> Option<ContentMerge> {
         match &self.resolution {
@@ -308,3 +341,35 @@ pub struct Options {
 
 pub(super) mod function;
 mod utils;
+pub mod apply_index_entries {
+
+    pub(super) mod function {
+        use crate::tree::Conflict;
+        use bstr::BString;
+
+        /// The error returned by [`apply_index_entries()`].
+        #[derive(Debug, thiserror::Error)]
+        #[allow(missing_docs)]
+        pub enum Error {
+            #[error(
+                "Could not find '{path}' in the index, even though it should have the non-conflicting variant of it."
+            )]
+            MissingPathInIndex { path: BString },
+        }
+
+        /// Returns `true` if `index` changed as we applied conflicting stages to it.
+        /// It's important that `index` matches the tree that was produced as part of the merge that also
+        /// brought about `conflicts`, or else this function will fail if it cannot find the path matching
+        /// the conflicting entries.
+        ///
+        /// Note that in practice, whenever there is a single [conflict], this function will return `true`.
+        /// Errors can only occour if `index` isn't the one created from the merged tree that produced the `conflicts`.
+        pub fn apply_index_entries(_conflicts: &[Conflict], index: &mut gix_index::State) -> Result<bool, Error> {
+            let len = index.entries().len();
+
+            Ok(index.entries().len() != len)
+        }
+    }
+    pub use function::Error;
+}
+pub use apply_index_entries::function::apply_index_entries;

gix-merge/src/tree/mod.rs

@@ -563,6 +563,7 @@ impl Conflict {
             resolution,
             ours: ours.clone(),
             theirs: theirs.clone(),
+            entries: Default::default(),
             map: match outer_map {
                 ConflictMapping::Original => map,
                 ConflictMapping::Swapped => map.swapped(),

gix-merge/src/tree/utils.rs

@@ -66,6 +66,20 @@ function baseline () (
     git -c merge.conflictStyle=$conflict_style merge-tree -z --write-tree --allow-unrelated-histories "$their_committish" "$our_committish" > "$merge_info" || :
     echo "$dir" "$conflict_style" "$their_commit_id" "$their_committish" "$our_commit_id" "$our_committish" "$merge_info" "$maybe_expected_tree" "$opt_deviation_message" >> ../baseline.cases
   fi
+
+  local index_path=.git/${conflict_style}-${our_committish}-${their_committish}.index
+  if [ ! -e $index_path ]; then
+    git checkout -f $our_committish
+    git merge -m m $their_committish || :
+    cp .git/index "$index_path"
+  fi
+
+  local index_path=.git/${conflict_style}-${their_committish}-${our_committish}.index
+  if [ ! -e $index_path ]; then
+    git checkout -f $their_committish
+    git merge -m m $our_committish || :
+    cp .git/index "$index_path"
+  fi
 )
 
 git init simple

gix-merge/tests/fixtures/generated-archives/tree-baseline.tar

@@ -96,6 +96,7 @@ pub struct Expectation {
     pub their_side_name: String,
     pub merge_info: MergeInfo,
     pub case_name: String,
+    pub index: gix_index::File,
     pub deviation: Option<Deviation>,
 }
 
@@ -129,7 +130,7 @@ impl Iterator for Expectations<'_> {
         let mut tokens = line.split(' ');
         let (
             Some(subdir),
-            Some(conflict_style),
+            Some(conflict_style_name),
             Some(our_commit_id),
             Some(our_side_name),
             Some(their_commit_id),
@@ -160,7 +161,7 @@ impl Iterator for Expectations<'_> {
         });
 
         let subdir_path = self.root.join(subdir);
-        let conflict_style = match conflict_style {
+        let conflict_style = match conflict_style_name {
             "merge" => ConflictStyle::Merge,
             "diff3" => ConflictStyle::Diff3,
             unknown => unreachable!("Unknown conflict style: '{unknown}'"),
@@ -170,6 +171,15 @@ impl Iterator for Expectations<'_> {
         let our_commit_id = gix_hash::ObjectId::from_hex(our_commit_id.as_bytes()).unwrap();
         let their_commit_id = gix_hash::ObjectId::from_hex(their_commit_id.as_bytes()).unwrap();
         let merge_info = parse_merge_info(std::fs::read_to_string(subdir_path.join(merge_info_filename)).unwrap());
+        let index = gix_index::File::at(
+            subdir_path
+                .join(".git")
+                .join(format!("{conflict_style_name}-{our_side_name}-{their_side_name}.index")),
+            gix_hash::Kind::Sha1,
+            false, /* skip hash */
+            Default::default(),
+        )
+        .expect("index should be present for each combination");
         Some(Expectation {
             root: subdir_path,
             conflict_style,
@@ -179,6 +189,7 @@ impl Iterator for Expectations<'_> {
             their_commit_id,
             their_side_name: their_side_name.to_owned(),
             merge_info,
+            index,
             case_name: format!(
                 "{subdir}-{}",
                 merge_info_filename
@@ -285,6 +296,30 @@ fn parse_info<'a>(mut lines: impl Iterator<Item = &'a str>) -> Option<ConflictIn
     Some(ConflictInfo { paths, kind, message })
 }
 
+#[derive(Debug, PartialEq, Eq)]
+pub struct DebugIndexEntry<'a> {
+    path: &'a BStr,
+    id: gix_hash::ObjectId,
+    mode: gix_index::entry::Mode,
+    stage: gix_index::entry::Stage,
+}
+
+pub fn clear_entries(state: &gix_index::State) -> Vec<DebugIndexEntry<'_>> {
+    state
+        .entries()
+        .iter()
+        .map(|entry| {
+            let path = entry.path(state);
+            DebugIndexEntry {
+                path,
+                id: entry.id,
+                mode: entry.mode,
+                stage: entry.stage(),
+            }
+        })
+        .collect()
+}
+
 pub fn visualize_tree(
     id: &gix_hash::oid,
     odb: &impl gix_object::Find,

gix-merge/tests/fixtures/tree-baseline.sh

@@ -32,6 +32,7 @@ fn run_baseline() -> crate::Result {
         their_side_name,
         merge_info,
         case_name,
+        index,
         deviation,
     } in baseline::Expectations::new(&root, &cases)
         .filter(|case| new_test.map_or(true, |prefix: &str| case.case_name.starts_with(prefix)))
@@ -98,6 +99,13 @@ fn run_baseline() -> crate::Result {
                 );
             }
         }
+
+        let actual_index = gix_index::State::from_tree(&actual_id, &odb, Default::default())?;
+        pretty_assertions::assert_eq!(
+            baseline::clear_entries(&actual_index),
+            baseline::clear_entries(&index),
+            "{case_name}: index mismatch"
+        );
     }
 
     assert_eq!(