Merge pull request #1734 from EliahKagan/nonfiles

Clarify and expand descriptions of `NonFile`s

Author: Byron

gitoxide-core/src/repository/clean.rs

@@ -188,9 +188,9 @@ pub(crate) mod function {
             }
 
             match disk_kind {
-                Kind::NonFile => {
+                Kind::Untrackable => {
                     if debug {
-                        writeln!(err, "DBG: skipped non-file at '{}'", entry.rela_path).ok();
+                        writeln!(err, "DBG: skipped untrackable entry at '{}'", entry.rela_path).ok();
                     }
                     continue;
                 }
@@ -265,7 +265,7 @@ pub(crate) mod function {
                     "WOULD remove"
                 },
                 suffix = match disk_kind {
-                    Kind::NonFile => unreachable!("always skipped earlier"),
+                    Kind::Untrackable => unreachable!("always skipped earlier"),
                     Kind::Directory if entry.property == Some(gix::dir::entry::Property::EmptyDirectory) => {
                         " empty"
                     }

gix-dir/src/entry.rs

@@ -26,11 +26,14 @@ pub enum Property {
 /// The kind of the entry, seated in their kinds available on disk.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Ord, PartialOrd)]
 pub enum Kind {
-    /// Something that is not a file, like a named pipe or character device.
+    /// Something that is not a regular file, directory, or symbolic link.
     ///
-    /// These can only exist in the filesystem.
-    NonFile,
-    /// The entry is a blob, executable or not.
+    /// These can only exist in the filesystem,
+    /// because Git repositories do not support them, thus they cannot be tracked.
+    /// Hence, they do not appear as blobs in a repository, and their type is not specifiable in a tree object.
+    /// Examples include named pipes (FIFOs), character devices, block devices, and sockets.
+    Untrackable,
+    /// The entry is a blob, representing a regular file, executable or not.
     File,
     /// The entry is a symlink.
     Symlink,
@@ -161,7 +164,7 @@ impl From<std::fs::FileType> for Kind {
         } else if value.is_file() {
             Kind::File
         } else {
-            Kind::NonFile
+            Kind::Untrackable
         }
     }
 }

gix-dir/tests/dir/walk.rs

@@ -68,8 +68,8 @@ fn one_top_level_fifo() {
 
     assert_eq!(
         entries,
-        &[entry("top", Untracked, NonFile),],
-        "Non-files are like normal files, but with a different state"
+        &[entry("top", Untracked, Untrackable),],
+        "Untrackable entries are like normal files, but with a different state"
     );
 }
 
@@ -103,11 +103,11 @@ fn fifo_in_traversal() {
         &[
             entry_nokind(".git", Pruned).with_property(DotGit).with_match(Always),
             entry("dir-with-file/nested-file", Untracked, File),
-            entry("dir/nested", Untracked, NonFile),
+            entry("dir/nested", Untracked, Untrackable),
             entry("file", Untracked, File),
-            entry("top", Untracked, NonFile),
+            entry("top", Untracked, Untrackable),
         ],
-        "Non-files only differ by their disk-kind"
+        "Untrackable entries only differ by their disk-kind"
     );
 }
 

gix-status/src/index_as_worktree/types.rs

@@ -103,7 +103,9 @@ impl Outcome {
 pub enum Change<T = (), U = ()> {
     /// This corresponding file does not exist in the worktree anymore.
     Removed,
-    /// The type of file changed compared to the worktree, i.e. a symlink is now a file, or a file was replaced with a named pipe.
+    /// The type of file changed compared to the worktree.
+    ///
+    /// Examples include when a symlink is now a regular file, or a regular file was replaced with a named pipe.
     ///
     /// ### Deviation
     ///

gix-status/src/index_as_worktree_with_renames/mod.rs

@@ -387,8 +387,8 @@ pub(super) mod function {
 
         impl<T, U> gix_dir::walk::Delegate for Delegate<'_, '_, T, U> {
             fn emit(&mut self, entry: EntryRef<'_>, collapsed_directory_status: Option<Status>) -> Action {
-                // Status never shows untracked non-files
-                if entry.disk_kind != Some(gix_dir::entry::Kind::NonFile) {
+                // Status never shows untracked entries of untrackable type
+                if entry.disk_kind != Some(gix_dir::entry::Kind::Untrackable) {
                     let entry = entry.to_owned();
                     self.tx.send(Event::DirEntry(entry, collapsed_directory_status)).ok();
                 }
@@ -469,7 +469,7 @@ pub(super) mod function {
                     ModificationOrDirwalkEntry::Modification(c) => c.entry.mode.to_tree_entry_mode(),
                     ModificationOrDirwalkEntry::DirwalkEntry { entry, .. } => entry.disk_kind.map(|kind| {
                         match kind {
-                            Kind::NonFile => {
+                            Kind::Untrackable => {
                                 // Trees are never tracked for rewrites, so we 'pretend'.
                                 gix_object::tree::EntryKind::Tree
                             }
@@ -507,7 +507,7 @@ pub(super) mod function {
             };
 
             Ok(match kind {
-                Kind::NonFile => {
+                Kind::Untrackable => {
                     // Go along with unreadable files, they are passed along without rename tracking.
                     return Ok(object_hash.null());
                 }