feat: add Repository::dirwalk_with_delegate().

That way it's possible to perform arbitrary directory walks,
useful for status, clean, and add.

Author: Byron

Cargo.lock

@@ -51,7 +51,7 @@ default = ["max-performance-safe", "comfort", "basic", "extras"]
 basic = ["blob-diff", "revision", "index"]
 
 ## Various additional features and capabilities that are not necessarily part of what most users would need.
-extras = ["worktree-stream", "worktree-archive", "revparse-regex", "mailmap", "excludes", "attributes", "worktree-mutation", "credentials", "interrupt", "status"]
+extras = ["worktree-stream", "worktree-archive", "revparse-regex", "mailmap", "excludes", "attributes", "worktree-mutation", "credentials", "interrupt", "status", "dirwalk"]
 
 ## Various progress-related features that improve the look of progress message units.
 comfort = ["gix-features/progress-unit-bytes", "gix-features/progress-unit-human-numbers"]
@@ -73,6 +73,9 @@ interrupt = ["dep:signal-hook", "gix-tempfile/signals"]
 ## Access to `.git/index` files.
 index = ["dep:gix-index"]
 
+## Support directory walks with Git-style annoations.
+dirwalk = ["dep:gix-dir"]
+
 ## Access to credential helpers, which provide credentials for URLs.
 # Note that `gix-negotiate` just piggibacks here, as 'credentials' is equivalent to 'fetch & push' right now.
 credentials = ["dep:gix-credentials", "dep:gix-prompt", "dep:gix-negotiate"]
@@ -251,6 +254,7 @@ gix-sec = { version = "^0.10.4", path = "../gix-sec" }
 gix-date = { version = "^0.8.3", path = "../gix-date" }
 gix-refspec = { version = "^0.22.0", path = "../gix-refspec" }
 gix-filter = { version = "^0.9.0", path = "../gix-filter", optional = true }
+gix-dir = { version = "^0.1.0", path = "../gix-dir", optional = true }
 
 gix-config = { version = "^0.35.0", path = "../gix-config" }
 gix-odb = { version = "^0.58.0", path = "../gix-odb" }

gix/Cargo.toml

@@ -0,0 +1,109 @@
+use gix_dir::walk::{EmissionMode, ForDeletionMode};
+
+/// Options for use in the [`Repository::dirwalk()`](crate::Repository::dirwalk()) function.
+///
+/// Note that all values start out disabled.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Ord, PartialOrd)]
+pub struct Options {
+    precompose_unicode: bool,
+    ignore_case: bool,
+
+    recurse_repositories: bool,
+    emit_pruned: bool,
+    emit_ignored: Option<EmissionMode>,
+    for_deletion: Option<ForDeletionMode>,
+    emit_tracked: bool,
+    emit_untracked: EmissionMode,
+    emit_empty_directories: bool,
+    classify_untracked_bare_repositories: bool,
+}
+
+/// Construction
+impl Options {
+    pub(crate) fn from_fs_caps(caps: gix_fs::Capabilities) -> Self {
+        Self {
+            precompose_unicode: caps.precompose_unicode,
+            ignore_case: caps.ignore_case,
+            recurse_repositories: false,
+            emit_pruned: false,
+            emit_ignored: None,
+            for_deletion: None,
+            emit_tracked: false,
+            emit_untracked: Default::default(),
+            emit_empty_directories: false,
+            classify_untracked_bare_repositories: false,
+        }
+    }
+}
+
+impl From<Options> for gix_dir::walk::Options {
+    fn from(v: Options) -> Self {
+        gix_dir::walk::Options {
+            precompose_unicode: v.precompose_unicode,
+            ignore_case: v.ignore_case,
+            recurse_repositories: v.recurse_repositories,
+            emit_pruned: v.emit_pruned,
+            emit_ignored: v.emit_ignored,
+            for_deletion: v.for_deletion,
+            emit_tracked: v.emit_tracked,
+            emit_untracked: v.emit_untracked,
+            emit_empty_directories: v.emit_empty_directories,
+            classify_untracked_bare_repositories: v.classify_untracked_bare_repositories,
+        }
+    }
+}
+
+impl Options {
+    /// If `toggle` is `true`, we will stop figuring out if any directory that is a candidate for recursion is also a nested repository,
+    /// which saves time but leads to recurse into it. If `false`, nested repositories will not be traversed.
+    pub fn recurse_repositories(mut self, toggle: bool) -> Self {
+        self.recurse_repositories = toggle;
+        self
+    }
+    /// If `toggle` is `true`, entries that are pruned and whose [Kind](gix_dir::entry::Kind) is known will be emitted.
+    pub fn emit_pruned(mut self, toggle: bool) -> Self {
+        self.emit_pruned = toggle;
+        self
+    }
+    /// If `value` is `Some(mode)`, entries that are ignored will be emitted according to the given `mode`.
+    /// If `None`, ignored entries will not be emitted at all.
+    pub fn emit_ignored(mut self, value: Option<EmissionMode>) -> Self {
+        self.emit_ignored = value;
+        self
+    }
+    /// When the walk is for deletion, `value` must be `Some(_)` to assure we don't collapse directories that have precious files in
+    /// them, and otherwise assure that no entries are observable that shouldn't be deleted.
+    /// If `None`, precious files are treated like expendable files, which is usually what you want when displaying them
+    /// for addition to the repository, and the collapse of folders can be more generous in relation to ignored files.
+    pub fn for_deletion(mut self, value: Option<ForDeletionMode>) -> Self {
+        self.for_deletion = value;
+        self
+    }
+    /// If `toggle` is `true`, we will also emit entries for tracked items. Otherwise these will remain 'hidden',
+    /// even if a pathspec directly refers to it.
+    pub fn emit_tracked(mut self, toggle: bool) -> Self {
+        self.emit_tracked = toggle;
+        self
+    }
+    /// Controls the way untracked files are emitted. By default, this is happening immediately and without any simplification.
+    pub fn emit_untracked(mut self, toggle: EmissionMode) -> Self {
+        self.emit_untracked = toggle;
+        self
+    }
+    /// If `toggle` is `true`, emit empty directories as well. Note that a directory also counts as empty if it has any
+    /// amount or depth of nested subdirectories, as long as none of them includes a file.
+    /// Thus, this makes leaf-level empty directories visible, as those don't have any content.
+    pub fn emit_empty_directories(mut self, toggle: bool) -> Self {
+        self.emit_empty_directories = toggle;
+        self
+    }
+
+    /// If `toggle` is `true`, we will not only find non-bare repositories in untracked directories, but also bare ones.
+    ///
+    /// Note that this is very costly, but without it, bare repositories will appear like untracked directories when collapsed,
+    /// and they will be recursed into.
+    pub fn classify_untracked_bare_repositories(mut self, toggle: bool) -> Self {
+        self.classify_untracked_bare_repositories = toggle;
+        self
+    }
+}

gix/src/dirwalk.rs

@@ -101,6 +101,8 @@ pub use gix_commitgraph as commitgraph;
 #[cfg(feature = "credentials")]
 pub use gix_credentials as credentials;
 pub use gix_date as date;
+#[cfg(feature = "dirwalk")]
+pub use gix_dir as dir;
 pub use gix_features as features;
 use gix_features::threading::OwnShared;
 pub use gix_features::{
@@ -174,6 +176,9 @@ pub use types::{Pathspec, PathspecDetached, Submodule};
 ///
 pub mod clone;
 pub mod commit;
+#[cfg(feature = "dirwalk")]
+///
+pub mod dirwalk;
 pub mod head;
 pub mod id;
 pub mod object;

gix/src/lib.rs

@@ -0,0 +1,94 @@
+use crate::bstr::BStr;
+use crate::{config, dirwalk, Repository};
+use std::path::Path;
+
+/// The error returned by [dirwalk()](Repository::dirwalk()).
+#[derive(Debug, thiserror::Error)]
+#[allow(missing_docs)]
+pub enum Error {
+    #[error(transparent)]
+    Walk(#[from] gix_dir::walk::Error),
+    #[error("A working tree is required to perform a directory walk")]
+    MissinWorkDir,
+    #[error(transparent)]
+    Excludes(#[from] config::exclude_stack::Error),
+    #[error(transparent)]
+    Pathspec(#[from] crate::pathspec::init::Error),
+    #[error(transparent)]
+    Prefix(#[from] gix_path::realpath::Error),
+    #[error(transparent)]
+    FilesystemOptions(#[from] config::boolean::Error),
+}
+
+impl Repository {
+    /// Return default options suitable for performing a directory walk on this repository.
+    ///
+    /// Used in conjunction with [`dirwalk()`](Self::dirwalk())
+    pub fn dirwalk_options(&self) -> Result<dirwalk::Options, config::boolean::Error> {
+        Ok(dirwalk::Options::from_fs_caps(self.filesystem_options()?))
+    }
+
+    /// Perform a directory walk configured with `options` under control of the `delegate`. Use `patterns` to
+    /// further filter entries.
+    ///
+    /// The `index` is used to determine if entries are tracked, and for excludes and attributes
+    /// lookup. Note that items will only count as tracked if they have the [`gix_index::entry::Flags::UPTODATE`]
+    /// flag set.
+    ///
+    /// See [`gix_dir::walk::delegate::Collect`] for a delegate that collects all seen entries.
+    pub fn dirwalk(
+        &self,
+        index: &gix_index::State,
+        patterns: impl IntoIterator<Item = impl AsRef<BStr>>,
+        options: dirwalk::Options,
+        delegate: &mut dyn gix_dir::walk::Delegate,
+    ) -> Result<gix_dir::walk::Outcome, Error> {
+        let workdir = self.work_dir().ok_or(Error::MissinWorkDir)?;
+        let mut excludes = self
+            .excludes(
+                index,
+                None,
+                crate::worktree::stack::state::ignore::Source::WorktreeThenIdMappingIfNotSkipped,
+            )?
+            .detach();
+        let (mut pathspec, mut maybe_attributes) = self
+            .pathspec(
+                patterns,
+                true, /* inherit ignore case */
+                index,
+                crate::worktree::stack::state::attributes::Source::WorktreeThenIdMapping,
+            )?
+            .into_parts();
+
+        let prefix = self.prefix()?.unwrap_or(Path::new(""));
+        let git_dir_realpath =
+            crate::path::realpath_opts(self.git_dir(), self.current_dir(), crate::path::realpath::MAX_SYMLINKS)?;
+        let fs_caps = self.filesystem_options()?;
+        let accelerate_lookup = fs_caps.ignore_case.then(|| index.prepare_icase_backing());
+        gix_dir::walk(
+            &workdir.join(prefix),
+            workdir,
+            gix_dir::walk::Context {
+                git_dir_realpath: git_dir_realpath.as_ref(),
+                current_dir: self.current_dir(),
+                index,
+                ignore_case_index_lookup: accelerate_lookup.as_ref(),
+                pathspec: &mut pathspec,
+                pathspec_attributes: &mut |relative_path, case, is_dir, out| {
+                    let stack = maybe_attributes
+                        .as_mut()
+                        .expect("can only be called if attributes are used in patterns");
+                    stack
+                        .set_case(case)
+                        .at_entry(relative_path, Some(is_dir), &self.objects)
+                        .map_or(false, |platform| platform.matching_attributes(out))
+                },
+                excludes: Some(&mut excludes),
+                objects: &self.objects,
+            },
+            options.into(),
+            delegate,
+        )
+        .map_err(Into::into)
+    }
+}

gix/src/repository/dirwalk.rs

@@ -43,6 +43,9 @@ mod config;
 #[cfg(feature = "blob-diff")]
 pub mod diff;
 ///
+#[cfg(feature = "dirwalk")]
+pub mod dirwalk;
+///
 #[cfg(feature = "attributes")]
 pub mod filter;
 mod graph;

gix/src/repository/mod.rs

@@ -15,6 +15,36 @@ mod state;
 mod submodule;
 mod worktree;
 
+#[cfg(feature = "dirwalk")]
+mod dirwalk {
+    use gix_dir::entry::Kind::*;
+    use gix_dir::walk::EmissionMode;
+
+    #[test]
+    fn basics() -> crate::Result {
+        let repo = crate::named_repo("make_basic_repo.sh")?;
+        let untracked_only = repo.dirwalk_options()?.emit_untracked(EmissionMode::CollapseDirectory);
+        let mut collect = gix::dir::walk::delegate::Collect::default();
+        let index = repo.index()?;
+        repo.dirwalk(&index, None::<&str>, untracked_only, &mut collect)?;
+        assert_eq!(
+            collect
+                .into_entries_by_path()
+                .into_iter()
+                .map(|e| (e.0.rela_path.to_string(), e.0.disk_kind.expect("kind is known")))
+                .collect::<Vec<_>>(),
+            [
+                ("bare-repo-with-index.git".to_string(), Directory),
+                ("bare.git".into(), Directory),
+                ("non-bare-repo-without-index".into(), Repository),
+                ("some".into(), Directory)
+            ],
+            "note how bare repos are just directories by default"
+        );
+        Ok(())
+    }
+}
+
 #[test]
 fn size_in_memory() {
     let actual_size = std::mem::size_of::<Repository>();