feat!: simplify walk() signature to compute root with pathspec prefix.

This makes the overall handling more unified, while assuring it's always
in the worktree.

Author: Byron

gix-dir/src/walk/function.rs

@@ -8,13 +8,13 @@ use crate::{entry, EntryRef};
 
 /// A function to perform a git-style, unsorted, directory walk.
 ///
-/// * `root` - the starting point of the walk and a readable directory.
-///     - Note that if the path leading to this directory or `root` itself is excluded, it will be provided to [`Delegate::emit()`]
-///       without further traversal.
-///     - If [`Options::precompose_unicode`] is enabled, this path must be precomposed.
-///     - Must be contained in `worktree_root`.
 /// * `worktree_root` - the top-most root of the worktree, which must be a prefix to `root`.
 ///     - If [`Options::precompose_unicode`] is enabled, this path must be precomposed.
+///     - The starting point of the traversal (traversal root) is calculated from by doing `worktree_root + pathspec.common_prefix()`.
+///     - Note that if the traversal root leading to this directory or it itself is excluded, it will be provided to [`Delegate::emit()`]
+///       without further traversal.
+///     - If [`Options::precompose_unicode`] is enabled, all involved paths must be precomposed.
+///     - Must be contained in `worktree_root`.
 /// * `ctx` - everything needed to classify the paths seen during the traversal.
 /// * `delegate` - an implementation of [`Delegate`] to control details of the traversal and receive its results.
 ///
@@ -36,14 +36,24 @@ use crate::{entry, EntryRef};
 /// or 0.25s for optimal multi-threaded performance, all in the WebKit directory with 388k items to traverse.
 /// Thus, the speedup could easily be 2x or more and thus worth investigating in due time.
 pub fn walk(
-    root: &Path,
     worktree_root: &Path,
     mut ctx: Context<'_>,
     options: Options,
     delegate: &mut dyn Delegate,
 ) -> Result<Outcome, Error> {
+    let root = match ctx.explicit_traversal_root {
+        Some(root) => root.to_owned(),
+        None => ctx
+            .pathspec
+            .longest_common_directory()
+            .and_then(|candidate| {
+                let candidate = worktree_root.join(candidate);
+                candidate.is_dir().then_some(candidate)
+            })
+            .unwrap_or_else(|| worktree_root.join(ctx.pathspec.prefix_directory())),
+    };
     let _span = gix_trace::coarse!("walk", root = ?root, worktree_root = ?worktree_root, options = ?options);
-    let (mut current, worktree_root_relative) = assure_no_symlink_in_root(worktree_root, root)?;
+    let (mut current, worktree_root_relative) = assure_no_symlink_in_root(worktree_root, &root)?;
     let mut out = Outcome::default();
     let mut buf = BString::default();
     let root_info = classify::root(
@@ -73,7 +83,7 @@ pub fn walk(
 
     let mut state = readdir::State::default();
     let _ = readdir::recursive(
-        root == worktree_root,
+        true,
         &mut current,
         &mut buf,
         root_info,
@@ -95,10 +105,9 @@ fn assure_no_symlink_in_root<'root>(
     root: &'root Path,
 ) -> Result<(PathBuf, Cow<'root, Path>), Error> {
     let mut current = worktree_root.to_owned();
-    let worktree_relative = root.strip_prefix(worktree_root).map_err(|_| Error::RootNotInWorktree {
-        worktree_root: worktree_root.to_owned(),
-        root: root.to_owned(),
-    })?;
+    let worktree_relative = root
+        .strip_prefix(worktree_root)
+        .expect("BUG: root was created from worktree_root + prefix");
     let worktree_relative = gix_path::normalize(worktree_relative.into(), Path::new(""))
         .ok_or(Error::NormalizeRoot { root: root.to_owned() })?;
 

gix-dir/src/walk/mod.rs

@@ -200,7 +200,7 @@ pub struct Context<'a> {
     /// in case-sensitive mode. It does, however, skip the directory hash creation (for looking
     /// up directories) unless `core.ignoreCase` is enabled.
     ///
-    /// We only use the hashmap when when available and when [`ignore_case`](Options::ignore_case) is enabled in the options.
+    /// We only use the hashmap when available and when [`ignore_case`](Options::ignore_case) is enabled in the options.
     pub ignore_case_index_lookup: Option<&'a gix_index::AccelerateLookup<'a>>,
     /// A pathspec to use as filter - we only traverse into directories if it matches.
     /// Note that the `ignore_case` setting it uses should match our [Options::ignore_case].
@@ -221,6 +221,15 @@ pub struct Context<'a> {
     pub excludes: Option<&'a mut gix_worktree::Stack>,
     /// Access to the object database for use with `excludes` - it's possible to access `.gitignore` files in the index if configured.
     pub objects: &'a dyn gix_object::Find,
+    /// If not `None`, override the traversal root that is computed and use this one instead.
+    ///
+    /// This can be useful if the traversal root may be a file, in which case the traversal will
+    /// still be returning possibly matching root entries.
+    ///
+    /// ### Panics
+    ///
+    /// If the `traversal_root` is not in the `worktree_root` passed to [walk()](crate::walk()).
+    pub explicit_traversal_root: Option<&'a std::path::Path>,
 }
 
 /// Additional information collected as outcome of [`walk()`](function::walk()).
@@ -242,8 +251,6 @@ pub enum Error {
     WorktreeRootIsFile { root: PathBuf },
     #[error("Traversal root '{}' contains relative path components and could not be normalized", root.display())]
     NormalizeRoot { root: PathBuf },
-    #[error("Traversal root '{}' must be literally contained in worktree root '{}'", root.display(), worktree_root.display())]
-    RootNotInWorktree { root: PathBuf, worktree_root: PathBuf },
     #[error("A symlink was found at component {component_index} of traversal root '{}' as seen from worktree root '{}'", root.display(), worktree_root.display())]
     SymlinkInRoot {
         root: PathBuf,

gix-dir/src/walk/readdir.rs

@@ -13,7 +13,7 @@ use crate::{entry, walk, Entry};
 /// Git mostly silently ignores IO errors and stops iterating seemingly quietly, while we error loudly.
 #[allow(clippy::too_many_arguments)]
 pub(super) fn recursive(
-    is_worktree_dir: bool,
+    is_top_level: bool,
     current: &mut PathBuf,
     current_bstr: &mut BString,
     current_info: classify::Outcome,
@@ -30,7 +30,7 @@ pub(super) fn recursive(
     })?;
 
     let mut num_entries = 0;
-    let mark = state.mark(is_worktree_dir);
+    let mark = state.mark(is_top_level);
     let mut prevent_collapse = false;
     for entry in entries {
         let entry = entry.map_err(|err| Error::DirEntry {
@@ -118,18 +118,18 @@ impl State {
     }
 
     /// Keep track of state we need to later resolve the state.
-    /// Worktree directories are special, as they don't fold.
-    fn mark(&self, is_worktree_dir: bool) -> Mark {
+    /// Top-level directories are special, as they don't fold.
+    fn mark(&self, is_top_level: bool) -> Mark {
         Mark {
             start_index: self.on_hold.len(),
-            is_worktree_dir,
+            is_top_level,
         }
     }
 }
 
 struct Mark {
     start_index: usize,
-    is_worktree_dir: bool,
+    is_top_level: bool,
 }
 
 impl Mark {
@@ -211,7 +211,7 @@ impl Mark {
         ctx: &mut Context<'_>,
         delegate: &mut dyn walk::Delegate,
     ) -> Option<Action> {
-        if self.is_worktree_dir {
+        if self.is_top_level {
             return None;
         }
         let (mut expendable, mut precious, mut untracked, mut entries, mut matching_entries) = (0, 0, 0, 0, 0);

gix-dir/tests/dir_walk_cwd.rs

@@ -1,7 +1,9 @@
-use crate::walk_utils::{collect, entry, fixture, options};
+use crate::walk_utils::{collect, entryps, fixture, options};
 use gix_dir::entry::Kind::File;
+use gix_dir::entry::PathspecMatch::Prefix;
 use gix_dir::entry::Status::Untracked;
 use gix_dir::walk;
+use pretty_assertions::assert_eq;
 use std::path::Path;
 
 pub mod walk_utils;
@@ -10,8 +12,9 @@ pub mod walk_utils;
 fn prefixes_work_as_expected() -> gix_testtools::Result {
     let root = fixture("only-untracked");
     std::env::set_current_dir(root.join("d"))?;
-    let (out, entries) = collect(&root, |keep, ctx| {
-        walk(&Path::new("..").join("d"), Path::new(".."), ctx, options(), keep)
+    let troot = Path::new("..").join("d");
+    let (out, entries) = collect(Path::new(".."), Some(&troot), |keep, ctx| {
+        walk(Path::new(".."), ctx, options(), keep)
     });
     assert_eq!(
         out,
@@ -24,9 +27,9 @@ fn prefixes_work_as_expected() -> gix_testtools::Result {
     assert_eq!(
         &entries,
         &[
-            entry("d/a", Untracked, File),
-            entry("d/b", Untracked, File),
-            entry("d/d/a", Untracked, File),
+            entryps("d/a", Untracked, File, Prefix),
+            entryps("d/b", Untracked, File, Prefix),
+            entryps("d/d/a", Untracked, File, Prefix),
         ]
     );
     Ok(())