feat!: Represent DotGit as ExtendedKind

This cleans up the model despite also making it harder to detect
whether something is a DotGit.

Author: Byron

gix-dir/src/entry.rs

@@ -2,40 +2,45 @@ use crate::walk::ForDeletionMode;
 use crate::{Entry, EntryRef};
 use std::borrow::Cow;
 
-/// The kind of the entry.
+/// A way of attaching additional information to an [Entry](crate::Entry) .
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Ord, PartialOrd)]
+pub enum Property {
+    /// The entry was named `.git`, matched according to the case-sensitivity rules of the repository.
+    DotGit,
+    /// The entry is a directory, and that directory is empty.
+    EmptyDirectory,
+    /// Always in conjunction with a directory on disk that is also known as cone-mode sparse-checkout exclude marker
+    /// - i.e. a directory that is excluded, so its whole content is excluded and not checked out nor is part of the index.
+    ///
+    /// Note that evne if the directory is empty, it will only have this state, not `EmptyDirectory`.
+    TrackedExcluded,
+}
+
+/// The kind of the entry, seated in their kinds available on disk.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Ord, PartialOrd)]
 pub enum Kind {
     /// The entry is a blob, executable or not.
     File,
     /// The entry is a symlink.
     Symlink,
-    /// A directory that contains no file or directory.
-    EmptyDirectory,
     /// The entry is an ordinary directory.
     ///
     /// Note that since we don't check for bare repositories, this could in fact be a collapsed
     /// bare repository. To be sure, check it again with [`gix_discover::is_git()`] and act accordingly.
     Directory,
-    /// The entry is a directory which *contains* a `.git` folder.
+    /// The entry is a directory which *contains* a `.git` folder, or a submodule entry in the index.
     Repository,
 }
 
 /// The kind of entry as obtained from a directory.
-///
-/// The order of variants roughly relates from cheap-to-compute to most expensive, as each level needs more tests to assert.
-/// Thus, `DotGit` is the cheapest, while `Untracked` is among the most expensive and one of the major outcomes of any
-/// [`walk`](crate::walk()) run.
-/// For example, if an entry was `Pruned`, we effectively don't know if it would have been `Untracked` as well as we stopped looking.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Ord, PartialOrd)]
 pub enum Status {
-    /// The filename of an entry was `.git`, which is generally pruned.
-    DotGit,
-    /// The provided pathspec prevented further processing as the path didn't match.
-    /// If this happens, no further checks are done so we wouldn't know if the path is also ignored for example (by mention in `.gitignore`).
+    /// The entry was removed from the walk due to its other properties, like [Flags] or [PathspecMatch]
+    ///
+    /// Note that entries flagged as `DotGit` directory will always be considered `Pruned`, but if they are
+    /// also ignored, in delete mode, they will be considered `Ignored` instead. This way, it's easier to remove them
+    /// while they will not be available for any interactions in read-only mode.
     Pruned,
-    /// Always in conjunction with a directory on disk that is also known as cone-mode sparse-checkout exclude marker - i.e. a directory
-    /// that is excluded, so its whole content is excluded and not checked out nor is part of the index.
-    TrackedExcluded,
     /// The entry is tracked in Git.
     Tracked,
     /// The entry is ignored as per `.gitignore` files and their rules.
@@ -52,7 +57,7 @@ pub enum Status {
 #[derive(Copy, Clone, PartialEq, Eq, Debug, Hash, Ord, PartialOrd)]
 pub enum PathspecMatch {
     /// The match happened because there wasn't any pattern, which matches all, or because there was a nil pattern or one with an empty path.
-    /// Thus this is not a match by merit.
+    /// Thus, this is not a match by merit.
     Always,
     /// A match happened, but the pattern excludes everything it matches, which means this entry was excluded.
     Excluded,
@@ -84,12 +89,24 @@ impl From<gix_pathspec::search::MatchKind> for PathspecMatch {
     }
 }
 
+impl From<gix_pathspec::search::Match<'_>> for PathspecMatch {
+    fn from(m: gix_pathspec::search::Match<'_>) -> Self {
+        if m.is_excluded() {
+            PathspecMatch::Excluded
+        } else {
+            m.kind.into()
+        }
+    }
+}
+
+/// Conversion
 impl EntryRef<'_> {
     /// Strip the lifetime to obtain a fully owned copy.
     pub fn to_owned(&self) -> Entry {
         Entry {
             rela_path: self.rela_path.clone().into_owned(),
             status: self.status,
+            property: self.property,
             disk_kind: self.disk_kind,
             index_kind: self.index_kind,
             pathspec_match: self.pathspec_match,
@@ -101,19 +118,22 @@ impl EntryRef<'_> {
         Entry {
             rela_path: self.rela_path.into_owned(),
             status: self.status,
+            property: self.property,
             disk_kind: self.disk_kind,
             index_kind: self.index_kind,
             pathspec_match: self.pathspec_match,
         }
     }
 }
 
+/// Conversion
 impl Entry {
     /// Obtain an [`EntryRef`] from this instance.
     pub fn to_ref(&self) -> EntryRef<'_> {
         EntryRef {
             rela_path: Cow::Borrowed(self.rela_path.as_ref()),
             status: self.status,
+            property: self.property,
             disk_kind: self.disk_kind,
             index_kind: self.index_kind,
             pathspec_match: self.pathspec_match,
@@ -136,10 +156,7 @@ impl From<std::fs::FileType> for Kind {
 impl Status {
     /// Return true if this status is considered pruned. A pruned entry is typically hidden from view due to a pathspec.
     pub fn is_pruned(&self) -> bool {
-        match self {
-            Status::DotGit | Status::TrackedExcluded | Status::Pruned => true,
-            Status::Ignored(_) | Status::Untracked | Status::Tracked => false,
-        }
+        matches!(&self, Status::Pruned)
     }
     /// Return `true` if `file_type` is a directory on disk and isn't ignored, and is not a repository.
     /// This implements the default rules of `git status`, which is good for a minimal traversal through
@@ -158,7 +175,7 @@ impl Status {
             return false;
         }
         match self {
-            Status::DotGit | Status::TrackedExcluded | Status::Pruned => false,
+            Status::Pruned => false,
             Status::Ignored(_) => {
                 for_deletion.map_or(false, |fd| {
                     matches!(
@@ -180,6 +197,6 @@ impl Kind {
 
     /// Return `true` if this is a directory on disk. Note that this is true for repositories as well.
     pub fn is_dir(&self) -> bool {
-        matches!(self, Kind::EmptyDirectory | Kind::Directory | Kind::Repository)
+        matches!(self, Kind::Directory | Kind::Repository)
     }
 }

gix-dir/src/lib.rs

@@ -29,14 +29,14 @@ pub struct EntryRef<'a> {
     /// Note that many entries with status `Pruned` will not show up as their kind hasn't yet been determined when they were
     /// pruned very early on.
     pub status: entry::Status,
-    /// Further specify the what the entry is on disk, similar to a file mode.
-    /// This is `None` if the entry was pruned by a pathspec that could not match, as we then won't invest the time to obtain
-    /// the kind of the entry on disk.
+    /// Additional properties of the entry.
+    pub property: Option<entry::Property>,
+    /// Further specify what the entry is on disk, similar to a file mode.
+    /// This is `None` if we decided it's not worth it to exit early and avoid trying to obtain this information.
     pub disk_kind: Option<entry::Kind>,
     /// The kind of entry according to the index, if tracked. *Usually* the same as `disk_kind`.
     pub index_kind: Option<entry::Kind>,
     /// Determines how the pathspec matched.
-    /// Can also be `None` if no pathspec matched, or if the status check stopped prior to checking for pathspec matches which is the case for [`entry::Status::DotGit`].
     /// Note that it can also be `Some(PathspecMatch::Excluded)` if a negative pathspec matched.
     pub pathspec_match: Option<entry::PathspecMatch>,
 }
@@ -48,7 +48,9 @@ pub struct Entry {
     pub rela_path: BString,
     /// The status of entry, most closely related to what we know from `git status`, but not the same.
     pub status: entry::Status,
-    /// Further specify the what the entry is on disk, similar to a file mode.
+    /// Additional flags that further clarify properties of the entry.
+    pub property: Option<entry::Property>,
+    /// Further specify what the entry is on disk, similar to a file mode.
     pub disk_kind: Option<entry::Kind>,
     /// The kind of entry according to the index, if tracked. *Usually* the same as `disk_kind`.
     pub index_kind: Option<entry::Kind>,

gix-dir/src/walk/classify.rs

@@ -1,4 +1,5 @@
-use crate::{entry, Entry};
+use crate::{entry, Entry, EntryRef};
+use std::borrow::Cow;
 
 use crate::entry::PathspecMatch;
 use crate::walk::{Context, Error, ForDeletionMode, Options};
@@ -61,7 +62,10 @@ pub fn root(
 pub struct Outcome {
     /// The computed status of an entry. It can be seen as aggregate of things we know about an entry.
     pub status: entry::Status,
-    /// What the entry is on disk, or `None` if we aborted the classification early.
+    /// An additional property.
+    pub property: Option<entry::Property>,
+    /// What the entry is on disk, or `None` if we aborted the classification early or an IO-error occurred
+    /// when querying the disk.
     ///
     /// Note that the index is used to avoid disk access provided its entries are marked uptodate
     /// (possibly by a prior call to update the status).
@@ -89,13 +93,27 @@ impl From<&Entry> for Outcome {
     fn from(e: &Entry) -> Self {
         Outcome {
             status: e.status,
+            property: e.property,
             disk_kind: e.disk_kind,
             index_kind: e.index_kind,
             pathspec_match: e.pathspec_match,
         }
     }
 }
 
+impl<'a> EntryRef<'a> {
+    pub(super) fn from_outcome(rela_path: Cow<'a, BStr>, info: crate::walk::classify::Outcome) -> Self {
+        EntryRef {
+            rela_path,
+            property: info.property,
+            status: info.status,
+            disk_kind: info.disk_kind,
+            index_kind: info.index_kind,
+            pathspec_match: info.pathspec_match,
+        }
+    }
+}
+
 /// Figure out what to do with `rela_path`, provided as worktree-relative path, with `disk_file_type` if it is known already
 /// as it helps to match pathspecs correctly, which can be different for directories.
 /// `path` is a disk-accessible variant of `rela_path` which is within the `worktree_root`, and will be modified temporarily but remain unchanged.
@@ -123,12 +141,36 @@ pub fn path(
     ctx: &mut Context<'_>,
 ) -> Result<Outcome, Error> {
     let mut out = Outcome {
-        status: entry::Status::DotGit,
+        status: entry::Status::Pruned,
+        property: None,
         disk_kind,
         index_kind: None,
         pathspec_match: None,
     };
     if is_eq(rela_path[filename_start_idx..].as_bstr(), ".git", ignore_case) {
+        out.pathspec_match = ctx
+            .pathspec
+            .pattern_matching_relative_path(
+                rela_path.as_bstr(),
+                disk_kind.map(|ft| ft.is_dir()),
+                ctx.pathspec_attributes,
+            )
+            .map(Into::into);
+        if for_deletion.is_some() {
+            if let Some(excluded) = ctx
+                .excludes
+                .as_mut()
+                .map_or(Ok(None), |stack| {
+                    stack
+                        .at_entry(rela_path.as_bstr(), disk_kind.map(|ft| ft.is_dir()), ctx.objects)
+                        .map(|platform| platform.excluded_kind())
+                })
+                .map_err(Error::ExcludesAccess)?
+            {
+                out.status = entry::Status::Ignored(excluded);
+            }
+        }
+        out.property = entry::Property::DotGit.into();
         return Ok(out);
     }
     let pathspec_could_match = rela_path.is_empty()
@@ -139,31 +181,25 @@ pub fn path(
         return Ok(out.with_status(entry::Status::Pruned));
     }
 
-    let (uptodate_index_kind, index_kind, mut maybe_status) = resolve_file_type_with_index(
+    let (uptodate_index_kind, index_kind, property) = resolve_file_type_with_index(
         rela_path,
         ctx.index,
         ctx.ignore_case_index_lookup.filter(|_| ignore_case),
     );
     let mut kind = uptodate_index_kind.or(disk_kind).or_else(on_demand_disk_kind);
 
-    maybe_status = maybe_status
-        .or_else(|| (index_kind.map(|k| k.is_dir()) == kind.map(|k| k.is_dir())).then_some(entry::Status::Tracked));
+    let maybe_status = if property.is_none() {
+        (index_kind.map(|k| k.is_dir()) == kind.map(|k| k.is_dir())).then_some(entry::Status::Tracked)
+    } else {
+        out.property = property;
+        Some(entry::Status::Pruned)
+    };
 
     // We always check the pathspec to have the value filled in reliably.
     out.pathspec_match = ctx
         .pathspec
-        .pattern_matching_relative_path(
-            rela_path.as_bstr(),
-            disk_kind.map(|ft| ft.is_dir()),
-            ctx.pathspec_attributes,
-        )
-        .map(|m| {
-            if m.is_excluded() {
-                PathspecMatch::Excluded
-            } else {
-                m.kind.into()
-            }
-        });
+        .pattern_matching_relative_path(rela_path.as_bstr(), kind.map(|ft| ft.is_dir()), ctx.pathspec_attributes)
+        .map(Into::into);
 
     let mut maybe_upgrade_to_repository = |current_kind, find_harder: bool| {
         if recurse_repositories {
@@ -258,8 +294,7 @@ pub fn path(
 
 /// Note that `rela_path` is used as buffer for convenience, but will be left as is when this function returns.
 /// Also note `maybe_file_type` will be `None` for entries that aren't up-to-date and files, for directories at least one entry must be uptodate.
-/// Returns `(maybe_file_type, Option<index_file_type>, Option(TrackedExcluded)`, with the last option being set only for sparse directories.
-/// `tracked_exclued` indicates it's a sparse directory was found.
+/// Returns `(maybe_file_type, Option<index_file_type>, flags)`, with the last option being a flag set only for sparse directories in the index.
 /// `index_file_type` is the type of `rela_path` as available in the index.
 ///
 /// ### Shortcoming
@@ -271,9 +306,9 @@ fn resolve_file_type_with_index(
     rela_path: &mut BString,
     index: &gix_index::State,
     ignore_case: Option<&gix_index::AccelerateLookup<'_>>,
-) -> (Option<entry::Kind>, Option<entry::Kind>, Option<entry::Status>) {
+) -> (Option<entry::Kind>, Option<entry::Kind>, Option<entry::Property>) {
     // TODO: either get this to work for icase as well, or remove the need for it. Logic is different in both branches.
-    let mut special_status = None;
+    let mut special_property = None;
 
     fn entry_to_kinds(entry: &gix_index::Entry) -> (Option<entry::Kind>, Option<entry::Kind>) {
         let kind = if entry.mode.is_submodule() {
@@ -352,14 +387,14 @@ fn resolve_file_type_with_index(
                         .filter(|_| kind.is_none())
                         .map_or(false, |idx| index.entries()[idx].mode.is_sparse())
                 {
-                    special_status = Some(entry::Status::TrackedExcluded);
+                    special_property = Some(entry::Property::TrackedExcluded);
                 }
                 (kind, is_tracked.then_some(entry::Kind::Directory))
             }
             Some(entry) => entry_to_kinds(entry),
         }
     };
-    (uptodate_kind, index_kind, special_status)
+    (uptodate_kind, index_kind, special_property)
 }
 
 fn is_eq(lhs: &BStr, rhs: impl AsRef<BStr>, ignore_case: bool) -> bool {

gix-dir/src/walk/function.rs

@@ -146,14 +146,7 @@ pub(super) fn can_recurse(
     if info.disk_kind.map_or(true, |k| !k.is_dir()) {
         return false;
     }
-    let entry = EntryRef {
-        rela_path: Cow::Borrowed(rela_path),
-        status: info.status,
-        disk_kind: info.disk_kind,
-        index_kind: info.index_kind,
-        pathspec_match: info.pathspec_match,
-    };
-    delegate.can_recurse(entry, for_deletion)
+    delegate.can_recurse(EntryRef::from_outcome(Cow::Borrowed(rela_path), info), for_deletion)
 }
 
 /// Possibly emit an entry to `for_each` in case the provided information makes that possible.
@@ -174,7 +167,7 @@ pub(super) fn emit_entry(
 ) -> Action {
     out.seen_entries += 1;
 
-    if (!emit_empty_directories && info.disk_kind == Some(entry::Kind::EmptyDirectory)
+    if (!emit_empty_directories && info.property == Some(entry::Property::EmptyDirectory)
         || !emit_tracked && info.status == entry::Status::Tracked)
         || emit_ignored.is_none() && matches!(info.status, entry::Status::Ignored(_))
         || !emit_pruned
@@ -187,14 +180,5 @@ pub(super) fn emit_entry(
     }
 
     out.returned_entries += 1;
-    delegate.emit(
-        EntryRef {
-            rela_path,
-            status: info.status,
-            disk_kind: info.disk_kind,
-            index_kind: info.index_kind,
-            pathspec_match: info.pathspec_match,
-        },
-        dir_status,
-    )
+    delegate.emit(EntryRef::from_outcome(rela_path, info), dir_status)
 }