feat!: replace conflict marker with detailed decoding of stages.

We also adjust the returned data structure to allow the input to be immutable,
which delegates entry updates to the caller.

This also paves the way for rename tracking, which requires free access to entries
for searching renames among the added and removed items, and/or copies among the added ones.

Author: Byron

gix-status/src/index_as_worktree/function.rs

@@ -1,7 +1,7 @@
 //! Changes between an index and a worktree.
 ///
 mod types;
-pub use types::{Change, Error, Options, Outcome, VisitEntry};
+pub use types::{Change, Conflict, EntryStatus, Error, Options, Outcome, VisitEntry};
 
 mod recorder;
 pub use recorder::{Record, Recorder};

gix-status/src/index_as_worktree/mod.rs

@@ -1,7 +1,7 @@
 use bstr::BStr;
 use gix_index as index;
 
-use crate::index_as_worktree::{Change, VisitEntry};
+use crate::index_as_worktree::{EntryStatus, VisitEntry};
 
 /// A record of a change.
 ///
@@ -14,10 +14,8 @@ pub struct Record<'index, T, U> {
     pub entry_index: usize,
     /// The path to the entry.
     pub relative_path: &'index BStr,
-    /// The change itself, or `None` if there is only a conflict.
-    pub change: Option<Change<T, U>>,
-    /// information about the conflict itself
-    pub conflict: bool,
+    /// The status information itself.
+    pub status: EntryStatus<T, U>,
 }
 
 /// Convenience implementation of [`VisitEntry`] that collects all non-trivial changes into a `Vec`.
@@ -33,20 +31,17 @@ impl<'index, T: Send, U: Send> VisitEntry<'index> for Recorder<'index, T, U> {
 
     fn visit_entry(
         &mut self,
+        _entries: &'index [index::Entry],
         entry: &'index index::Entry,
         entry_index: usize,
-        rela_path: &'index BStr,
-        change: Option<Change<Self::ContentChange, Self::SubmoduleStatus>>,
-        conflict: bool,
+        relative_path: &'index BStr,
+        status: EntryStatus<Self::ContentChange, Self::SubmoduleStatus>,
     ) {
-        if conflict || change.is_some() {
-            self.records.push(Record {
-                entry,
-                entry_index,
-                relative_path: rela_path,
-                change,
-                conflict,
-            })
-        }
+        self.records.push(Record {
+            entry,
+            entry_index,
+            relative_path,
+            status,
+        })
     }
 }

gix-status/src/index_as_worktree/recorder.rs

@@ -53,9 +53,11 @@ pub struct Outcome {
     pub entries_skipped_by_entry_flags: usize,
     /// The amount of times we queried symlink-metadata for a file on disk.
     pub symlink_metadata_calls: usize,
-    /// The amount of entries whose stats have been updated as its modification couldn't be determined without an expensive calculation.
+    /// The amount of entries whose stats would need to be updated as its modification couldn't be determined without
+    /// an expensive calculation.
     ///
     /// With these updates, this calculation will be avoided next time the status runs.
+    /// Note that the stat updates are delegated to the caller.
     pub entries_updated: usize,
     /// The amount of entries that were considered racy-clean - they will need thorough checking to see if they are truly clean,
     /// i.e. didn't change.
@@ -79,7 +81,7 @@ impl Outcome {
 }
 
 /// How an index entry needs to be changed to obtain the destination worktree state, i.e. `entry.apply(this_change) == worktree-entry`.
-#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Debug)]
+#[derive(Clone, PartialEq, Eq, PartialOrd, Ord, Debug)]
 pub enum Change<T = (), U = ()> {
     /// This corresponding file does not exist in the worktree anymore.
     Removed,
@@ -95,6 +97,11 @@ pub enum Change<T = (), U = ()> {
         /// If there is no content change and only the executable bit
         /// changed then this is `None`.
         content_change: Option<T>,
+        /// If true, the caller is expected to set [entry.stat.size = 0](gix_index::entry::Stat::size) to assure this
+        /// otherwise racily clean entry can still be detected as dirty next time this is called, but this time without
+        /// reading it from disk to hash it. It's a performance optimization and not doing so won't change the correctness
+        /// of the operation.
+        set_entry_stat_size_zero: bool,
     },
     /// A submodule is initialized and checked out, and there was modification to either:
     ///
@@ -105,28 +112,73 @@ pub enum Change<T = (), U = ()> {
     /// The exact nature of the modification is handled by the caller which may retain information per submodule or
     /// re-compute details as needed when seeing this variant.
     SubmoduleModification(U),
-    /// An index entry that correspond to an untracked worktree file marked with `git add --intent-to-add`.
+}
+
+/// Information about an entry.
+#[derive(Clone, PartialEq, Eq, PartialOrd, Ord, Debug)]
+pub enum EntryStatus<T = (), U = ()> {
+    /// The entry is in a conflicting state, and we didn't collect any more information about it.
+    Conflict(Conflict),
+    /// There is no conflict and a change was discovered.
+    Change(Change<T, U>),
+    /// The entry didn't change, but its state caused extra work that can be avoided next time if its stats would be updated to the
+    /// given stat.
+    NeedsUpdate(
+        /// The new stats which represent what's currently in the working tree. If these replace the current stats in the entry,
+        /// next time this operation runs we can determine the actual state much faster.
+        gix_index::entry::Stat,
+    ),
+    /// An index entry that corresponds to an untracked worktree file marked with `git add --intent-to-add`.
     ///
-    /// This means it's not available in the object database yet
-    /// even though now an entry exists that represents the worktree file.
+    /// This means it's not available in the object database yet even though now an entry exists that represents the worktree file.
+    /// The entry represents the promise of adding a new file, no matter the actual stat or content.
+    /// Effectively this means nothing changed.
+    /// This also means the file is still present, and that no detailed change checks were performed.
     IntentToAdd,
 }
 
-/// Observe changes by comparing an index entry to the worktree or another index.
+impl<T, U> From<Change<T, U>> for EntryStatus<T, U> {
+    fn from(value: Change<T, U>) -> Self {
+        EntryStatus::Change(value)
+    }
+}
+
+/// Describes a conflicting entry as comparison between 'our' version and 'their' version of it.
+///
+/// If one side isn't specified, it is assumed to have modified the entry. In general, there would be no conflict
+/// if both parties ended up in the same state.
+#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Debug)]
+pub enum Conflict {
+    /// Both deleted a different version of the entry.
+    BothDeleted,
+    /// We added, they modified, ending up in different states.
+    AddedByUs,
+    /// They deleted the entry, we modified it.
+    DeletedByThem,
+    /// They added the entry, we modified it, ending up in different states.
+    AddedByThem,
+    /// We deleted the entry, they modified it, ending up in different states.
+    DeletedByUs,
+    /// Both added the entry in different states.
+    BothAdded,
+    /// Both modified the entry, ending up in different states.
+    BothModified,
+}
+
+/// Observe the status of an entry by comparing an index entry to the worktree.
 pub trait VisitEntry<'index> {
     /// Data generated by comparing an entry with a file.
     type ContentChange;
     /// Data obtained when checking the submodule status.
     type SubmoduleStatus;
-    /// Observe the `change` of `entry` at the repository-relative `rela_path` at `entry_index`
-    /// (relative to the complete list of all index entries), indicating whether or not it has a `conflict`.
-    /// If `change` is `None`, there is no change.
+    /// Observe the `status` of `entry` at the repository-relative `rela_path` at `entry_index`
+    /// (for accessing `entry` and surrounding in the complete list of `entries`).
     fn visit_entry(
         &mut self,
+        entries: &'index [gix_index::Entry],
         entry: &'index gix_index::Entry,
         entry_index: usize,
         rela_path: &'index BStr,
-        change: Option<Change<Self::ContentChange, Self::SubmoduleStatus>>,
-        conflict: bool,
+        status: EntryStatus<Self::ContentChange, Self::SubmoduleStatus>,
     );
 }

gix-status/src/index_as_worktree/types.rs

@@ -0,0 +1,67 @@
+#!/bin/bash
+set -eu -o pipefail
+
+(git init both-deleted && cd both-deleted
+  echo test > file
+  git add file && git commit -m file &&
+  git branch alt && git mv file added-by-them
+  git commit -m "file renamed in added-by-them" && git checkout alt
+  git mv file added-by-us
+  git commit -m "file renamed in added-by-us"
+  git reset --hard alt
+  git merge main || :
+)
+
+(git init deleted-by-us && cd deleted-by-us
+		git init
+		>file && git add file && git commit -m "initial"
+		echo change >> file && git commit -am "modify"
+		git checkout -b side HEAD^
+		git rm file
+		git commit -m delete
+		git merge main || :
+)
+
+(git init deleted-by-them && cd deleted-by-them
+  echo "This is some content." > file
+  git add file
+  git commit -m "Initial commit"
+  git checkout -b conflict
+  git rm file
+  git commit -m "Delete file in feature branch"
+  git checkout main
+  echo "Modified by main branch." >> file
+  git add file
+  git commit -m "Modified file in main branch"
+  git merge conflict || :
+)
+
+(git init both-modified && cd both-modified
+  git init
+  > file && git add file && git commit -m "init"
+
+  git checkout -b conflict
+  echo conflicting >> file && git commit -am "alt-change"
+
+  git checkout main
+  echo other >> file && git commit -am "change"
+
+  git merge conflict || :
+)
+
+(git init both-added && cd both-added
+  git init
+  set -x
+	echo init >> deleted-by-them && git add . && git commit -m "init"
+
+	git checkout -b second_branch
+	git rm deleted-by-them
+	git commit -m "deleted-by-them deleted on second_branch"
+	echo second > both-added && git add . && git commit -m second
+
+	git checkout main
+	echo on_second > deleted-by-them && git commit -am "on second"
+	echo main > both-added && git add . && git commit -m main
+
+	git merge second_branch || :
+)

gix-status/tests/fixtures/conflicts.sh

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:855ef3e8f1cf518daab18a572ad9dc4a7c532a213d1b9f8a78f32f5346b518a2
+size 19036