frame for dir walking and handling of untracked files.

Author: Byron

Cargo.lock

@@ -309,3 +309,5 @@ GIT_SSH_COMMAND="ssh -VVV" \
 git <command>
 ```
 
+Consider adding `GIT_TRACE2_PERF=1` (possibly add `GIT_TRACE2_PERF_BRIEF=1` for brevity) as well for statistics and variables 
+(see [their source for more](https://github.com/git/git/blob/b50a608ba20348cb3dfc16a696816d51780e3f0f/trace2/tr2_sysenv.c#L50).

DEVELOPMENT.md

@@ -12,3 +12,18 @@ rust-version = "1.65"
 doctest = false
 
 [dependencies]
+gix-index = { version = "^0.29.0", path = "../gix-index" }
+gix-discover = { version = "^0.29.0", path = "../gix-discover" }
+gix-path = { version = "^0.10.4", path = "../gix-path" }
+gix-pathspec = { version = "^0.6.0", path = "../gix-pathspec" }
+gix-worktree = { version = "^0.30.0", path = "../gix-worktree", default-features = false }
+gix-object = { version = "^0.41.0", path = "../gix-object" }
+gix-ignore = { version = "^0.11.0", path = "../gix-ignore" }
+gix-utils = { version = "^0.1.9", path = "../gix-utils", features = ["bstr"] }
+
+bstr = { version = "1.5.0", default-features = false }
+thiserror = "1.0.56"
+
+[dev-dependencies]
+gix-testtools = { path = "../tests/tools" }
+gix-fs = { path = "../gix-fs" }

gix-dir/Cargo.toml

@@ -0,0 +1,102 @@
+use crate::{Entry, EntryRef};
+
+/// The kind of the entry.
+#[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,
+    /// The entry is an ordinary directory.
+    Directory,
+    /// The entry is a directory which *contains* a `.git` folder.
+    Repository,
+}
+
+/// The kind of entry as obtained from a directory.
+#[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, or it is a `.git` directory.
+    /// 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`).
+    Pruned,
+    /// The entry is ignored as per `.gitignore` files and their rules.
+    ///
+    /// If this is a directory, then its entire contents is ignored. Otherwise, possibly due to configuration, individual ignored files are listed.
+    Ignored(gix_ignore::Kind),
+    /// The entry is not tracked by git yet, it was not found in the [index](gix_index::State).
+    ///
+    /// If it's a directory, the entire directory contents is untracked.
+    Untracked,
+    /// The entry is tracked in git.
+    Tracked,
+}
+
+impl Status {
+    /// Returns `true` if this entry will generally not be traversed into.
+    pub fn is_pruned(&self) -> bool {
+        matches!(self, Status::DotGit | Status::Pruned)
+    }
+}
+
+impl EntryRef<'_> {
+    /// Strip the lifetime to obtain a fully owned copy.
+    pub fn to_owned(&self) -> Entry {
+        Entry {
+            rela_path: self.rela_path.to_owned(),
+            status: self.status,
+            kind: self.kind,
+        }
+    }
+}
+
+impl Entry {
+    /// Obtain an [`EntryRef`] from this instance.
+    pub fn to_ref(&self) -> EntryRef<'_> {
+        EntryRef {
+            rela_path: self.rela_path.as_ref(),
+            status: self.status,
+            kind: self.kind,
+        }
+    }
+}
+
+impl From<std::fs::FileType> for Kind {
+    fn from(value: std::fs::FileType) -> Self {
+        if value.is_dir() {
+            Kind::Directory
+        } else if value.is_symlink() {
+            Kind::Symlink
+        } else {
+            Kind::File
+        }
+    }
+}
+
+impl Status {
+    /// Return `true` if this directory isn't ignored, and is not a repository.
+    /// This implements the default rules of `git status`, which is good for a minimal traversal through
+    /// tracked and non-ignored portions of a worktree.
+    pub fn can_recurse(&self, file_type: Option<Kind>) -> bool {
+        if file_type.map_or(true, |ft| !ft.is_recursable_dir()) {
+            return false;
+        }
+        match self {
+            Status::DotGit | Status::Pruned => false,
+            Status::Ignored(_) => false, // TODO: needs option to allow recursing into ignored directories
+            Status::Untracked | Status::Tracked => true,
+        }
+    }
+}
+
+impl Kind {
+    fn is_recursable_dir(&self) -> bool {
+        matches!(self, Kind::Directory)
+    }
+
+    /// 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::Directory | Kind::Repository)
+    }
+}

gix-dir/src/entry.rs

@@ -1,3 +1,40 @@
 //! A crate for handling a git-style directory walk.
-#![deny(rust_2018_idioms)]
+#![deny(missing_docs, rust_2018_idioms)]
 #![forbid(unsafe_code)]
+use bstr::{BStr, BString};
+
+/// A directory entry, typically obtained using [`walk()`].
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Ord, PartialOrd)]
+pub struct EntryRef<'a> {
+    /// The repository-relative path at which the file or directory could be found, with unix-style component separators.
+    ///
+    /// To obtain the respective file, join it with the `worktree_root` passed to [`walk()`].
+    /// The rationale here is that this is a compressed and normalized version compared to the paths we would otherwise get,
+    /// which is preferable especially when converted to [`Entry`] due to lower memory requirements.
+    ///
+    /// This also means that the original path to be presented to the user needs to be computed separately.
+    pub rela_path: &'a BStr,
+    /// 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, similar to a file mode.
+    pub kind: entry::Kind,
+}
+
+/// Just like [`EntryRef`], but with all fields owned (and thus without a lifetime to consider).
+#[derive(Debug, Clone, PartialEq, Eq, Hash, Ord, PartialOrd)]
+pub struct Entry {
+    /// The path at which the file or directory could be found, always with `root` as prefix,
+    /// the first parameter of [`walk()`].
+    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, similar to a file mode.
+    pub kind: entry::Kind,
+}
+
+///
+pub mod entry;
+
+///
+pub mod walk;
+pub use walk::function::walk;