feat!: Provide a wrapper for gix_worktree::Stack for simpler attribute queries.

Author: Byron

gix/src/attribute_stack.rs

@@ -0,0 +1,69 @@
+use crate::bstr::BStr;
+use crate::types::AttributeStack;
+use crate::Repository;
+use gix_odb::FindExt;
+use std::ops::{Deref, DerefMut};
+
+/// Lifecycle
+impl<'repo> AttributeStack<'repo> {
+    /// Create a new instance from a `repo` and the underlying pre-configured `stack`.
+    ///
+    /// Note that this type is typically created by [`Repository::attributes()`] or [`Repository::attributes_only()`].
+    pub fn new(stack: gix_worktree::Stack, repo: &'repo Repository) -> Self {
+        AttributeStack { repo, inner: stack }
+    }
+
+    /// Detach the repository and return the underlying plumbing datatype.
+    pub fn detach(self) -> gix_worktree::Stack {
+        self.inner
+    }
+}
+
+impl Deref for AttributeStack<'_> {
+    type Target = gix_worktree::Stack;
+
+    fn deref(&self) -> &Self::Target {
+        &self.inner
+    }
+}
+
+impl DerefMut for AttributeStack<'_> {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        &mut self.inner
+    }
+}
+
+/// Platform retrieval
+impl<'repo> AttributeStack<'repo> {
+    /// Append the `relative` path to the root directory of the cache and efficiently create leading directories, while assuring that no
+    /// symlinks are in that path.
+    /// Unless `is_dir` is known with `Some(…)`, then `relative` points to a directory itself in which case the entire resulting
+    /// path is created as directory. If it's not known it is assumed to be a file.
+    ///
+    /// Provide access to cached information for that `relative` path via the returned platform.
+    pub fn at_path(
+        &mut self,
+        relative: impl AsRef<std::path::Path>,
+        is_dir: Option<bool>,
+    ) -> std::io::Result<gix_worktree::stack::Platform<'_>> {
+        self.inner
+            .at_path(relative, is_dir, |id, buf| self.repo.objects.find_blob(id, buf))
+    }
+
+    /// Obtain a platform for lookups from a repo-`relative` path, typically obtained from an index entry. `is_dir` should reflect
+    /// whether it's a directory or not, or left at `None` if unknown.
+    ///
+    /// If `relative` ends with `/` and `is_dir` is `None`, it is automatically assumed to be a directory.
+    ///
+    /// ### Panics
+    ///
+    /// - on illformed UTF8 in `relative`
+    pub fn at_entry<'r>(
+        &mut self,
+        relative: impl Into<&'r BStr>,
+        is_dir: Option<bool>,
+    ) -> std::io::Result<gix_worktree::stack::Platform<'_>> {
+        self.inner
+            .at_entry(relative, is_dir, |id, buf| self.repo.objects.find_blob(id, buf))
+    }
+}

gix/src/lib.rs

@@ -117,6 +117,8 @@ mod ext;
 ///
 pub mod prelude;
 
+mod attribute_stack;
+
 ///
 pub mod path;
 
@@ -129,7 +131,7 @@ pub(crate) type Config = OwnShared<gix_config::File<'static>>;
 
 mod types;
 pub use types::{
-    Commit, Head, Id, Object, ObjectDetached, Pathspec, Reference, Remote, Repository, Submodule, Tag,
+    AttributeStack, Commit, Head, Id, Object, ObjectDetached, Pathspec, Reference, Remote, Repository, Submodule, Tag,
     ThreadSafeRepository, Tree, Worktree,
 };
 

gix/src/pathspec.rs

@@ -2,7 +2,7 @@
 use gix_odb::FindExt;
 pub use gix_pathspec::*;
 
-use crate::{bstr::BStr, Pathspec, Repository};
+use crate::{bstr::BStr, AttributeStack, Pathspec, Repository};
 
 ///
 pub mod init {
@@ -59,21 +59,28 @@ impl<'repo> Pathspec<'repo> {
             )?,
         )?;
         let cache = needs_cache.then(make_attributes).transpose()?;
-        Ok(Self { repo, search, cache })
+        Ok(Self {
+            repo,
+            search,
+            stack: cache,
+        })
     }
     /// Turn ourselves into the functional parts for direct usage.
-    /// Note that the [`cache`](gix_worktree::Stack) is only set if one of the [`search` patterns](Search)
+    /// Note that the [`cache`](AttributeStack) is only set if one of the [`search` patterns](Search)
     /// is specifying attributes to match for.
-    pub fn into_parts(self) -> (Search, Option<gix_worktree::Stack>) {
-        (self.search, self.cache)
+    pub fn into_parts(self) -> (Search, Option<AttributeStack<'repo>>) {
+        (
+            self.search,
+            self.stack.map(|stack| AttributeStack::new(stack, self.repo)),
+        )
     }
 }
 
 /// Access
 impl<'repo> Pathspec<'repo> {
     /// Return the attributes cache which is used when matching attributes in pathspecs, or `None` if none of the pathspecs require that.
     pub fn attributes(&self) -> Option<&gix_worktree::Stack> {
-        self.cache.as_ref()
+        self.stack.as_ref()
     }
 
     /// Return the search itself which can be used for matching paths or accessing the actual patterns that will be used.
@@ -99,8 +106,8 @@ impl<'repo> Pathspec<'repo> {
     ) -> Option<gix_pathspec::search::Match<'_>> {
         self.search
             .pattern_matching_relative_path(relative_path, is_dir, |relative_path, case, is_dir, out| {
-                let cache = self.cache.as_mut().expect("initialized in advance");
-                cache
+                let stack = self.stack.as_mut().expect("initialized in advance");
+                stack
                     .set_case(case)
                     .at_entry(relative_path, Some(is_dir), |id, buf| {
                         self.repo.objects.find_blob(id, buf)

gix/src/repository/attributes.rs

@@ -1,5 +1,5 @@
 //! exclude information
-use crate::{config, Repository};
+use crate::{config, AttributeStack, Repository};
 
 /// The error returned by [`Repository::attributes()`].
 #[derive(Debug, thiserror::Error)]
@@ -24,15 +24,13 @@ impl Repository {
     ///
     /// * `$XDG_CONFIG_HOME/…/ignore|attributes` if `core.excludesFile|attributesFile` is *not* set, otherwise use the configured file.
     /// * `$GIT_DIR/info/exclude|attributes` if present.
-    // TODO: test, provide higher-level custom Cache wrapper that is much easier to use and doesn't panic when accessing entries
-    //       by non-relative path.
     pub fn attributes(
         &self,
         index: &gix_index::State,
         attributes_source: gix_worktree::stack::state::attributes::Source,
         ignore_source: gix_worktree::stack::state::ignore::Source,
         exclude_overrides: Option<gix_ignore::Search>,
-    ) -> Result<gix_worktree::Stack, Error> {
+    ) -> Result<AttributeStack<'_>, Error> {
         let case = if self.config.ignore_case {
             gix_glob::pattern::Case::Fold
         } else {
@@ -48,13 +46,16 @@ impl Repository {
                 .assemble_exclude_globals(self.git_dir(), exclude_overrides, ignore_source, &mut buf)?;
         let state = gix_worktree::stack::State::AttributesAndIgnoreStack { attributes, ignore };
         let attribute_list = state.id_mappings_from_index(index, index.path_backing(), case);
-        Ok(gix_worktree::Stack::new(
-            // this is alright as we don't cause mutation of that directory, it's virtual.
-            self.work_dir().unwrap_or(self.git_dir()),
-            state,
-            case,
-            buf,
-            attribute_list,
+        Ok(AttributeStack::new(
+            gix_worktree::Stack::new(
+                // this is alright as we don't cause mutation of that directory, it's virtual.
+                self.work_dir().unwrap_or(self.git_dir()),
+                state,
+                case,
+                buf,
+                attribute_list,
+            ),
+            self,
         ))
     }
 
@@ -63,7 +64,7 @@ impl Repository {
         &self,
         index: &gix_index::State,
         attributes_source: gix_worktree::stack::state::attributes::Source,
-    ) -> Result<gix_worktree::Stack, config::attribute_stack::Error> {
+    ) -> Result<AttributeStack<'_>, config::attribute_stack::Error> {
         let case = if self.config.ignore_case {
             gix_glob::pattern::Case::Fold
         } else {
@@ -76,13 +77,16 @@ impl Repository {
         )?;
         let state = gix_worktree::stack::State::AttributesStack(attributes);
         let attribute_list = state.id_mappings_from_index(index, index.path_backing(), case);
-        Ok(gix_worktree::Stack::new(
-            // this is alright as we don't cause mutation of that directory, it's virtual.
-            self.work_dir().unwrap_or(self.git_dir()),
-            state,
-            case,
-            buf,
-            attribute_list,
+        Ok(AttributeStack::new(
+            gix_worktree::Stack::new(
+                // this is alright as we don't cause mutation of that directory, it's virtual.
+                self.work_dir().unwrap_or(self.git_dir()),
+                state,
+                case,
+                buf,
+                attribute_list,
+            ),
+            self,
         ))
     }
 

gix/src/repository/filter.rs

@@ -59,6 +59,6 @@ impl Repository {
             )?;
             (cache, IndexPersistedOrInMemory::Persisted(index))
         };
-        Ok((filter::Pipeline::new(self, cache)?, index))
+        Ok((filter::Pipeline::new(self, cache.detach())?, index))
     }
 }

gix/src/repository/pathspec.rs

@@ -1,6 +1,6 @@
 use gix_pathspec::MagicSignature;
 
-use crate::{bstr::BStr, config::cache::util::ApplyLeniencyDefault, Pathspec, Repository};
+use crate::{bstr::BStr, config::cache::util::ApplyLeniencyDefault, AttributeStack, Pathspec, Repository};
 
 impl Repository {
     /// Create a new pathspec abstraction that allows to conduct searches using `patterns`.
@@ -20,7 +20,9 @@ impl Repository {
         attributes_source: gix_worktree::stack::state::attributes::Source,
     ) -> Result<Pathspec<'_>, crate::pathspec::init::Error> {
         Pathspec::new(self, patterns, inherit_ignore_case, || {
-            self.attributes_only(index, attributes_source).map_err(Into::into)
+            self.attributes_only(index, attributes_source)
+                .map(AttributeStack::detach)
+                .map_err(Into::into)
         })
     }
 

gix/src/repository/worktree.rs

@@ -75,7 +75,9 @@ impl crate::Repository {
         // TODO(perf): when loading a non-HEAD tree, we effectively traverse the tree twice. This is usually fast though, and sharing
         //             an object cache between the copies of the ODB handles isn't trivial and needs a lock.
         let index = self.index_from_tree(&id)?;
-        let mut cache = self.attributes_only(&index, gix_worktree::stack::state::attributes::Source::IdMapping)?;
+        let mut cache = self
+            .attributes_only(&index, gix_worktree::stack::state::attributes::Source::IdMapping)?
+            .detach();
         let pipeline =
             gix_filter::Pipeline::new(cache.attributes_collection(), crate::filter::Pipeline::options(self)?);
         let objects = self.objects.clone().into_arc().expect("TBD error handling");

gix/src/submodule/mod.rs

@@ -61,11 +61,14 @@ impl<'repo> SharedState<'repo> {
                 .modules
                 .is_active_platform(&self.repo.config.resolved, self.repo.config.pathspec_defaults()?)?;
             let index = self.index()?;
-            let attributes = self.repo.attributes_only(
-                &index,
-                gix_worktree::stack::state::attributes::Source::WorktreeThenIdMapping
-                    .adjust_for_bare(self.repo.is_bare()),
-            )?;
+            let attributes = self
+                .repo
+                .attributes_only(
+                    &index,
+                    gix_worktree::stack::state::attributes::Source::WorktreeThenIdMapping
+                        .adjust_for_bare(self.repo.is_bare()),
+                )?
+                .detach();
             *state = Some(IsActiveState { platform, attributes });
         }
         Ok(RefMut::map_split(state, |opt| {

gix/src/types.rs

@@ -208,7 +208,7 @@ pub struct Remote<'repo> {
 pub struct Pathspec<'repo> {
     pub(crate) repo: &'repo Repository,
     /// The cache to power attribute access. It's only initialized if we have a pattern with attributes.
-    pub(crate) cache: Option<gix_worktree::Stack>,
+    pub(crate) stack: Option<gix_worktree::Stack>,
     /// The prepared search to use for checking matches.
     pub(crate) search: gix_pathspec::Search,
 }
@@ -219,3 +219,9 @@ pub struct Submodule<'repo> {
     pub(crate) state: Rc<crate::submodule::SharedState<'repo>>,
     pub(crate) name: BString,
 }
+
+/// A utility to access `.gitattributes` and `.gitignore` information efficiently.
+pub struct AttributeStack<'repo> {
+    pub(crate) repo: &'repo Repository,
+    pub(crate) inner: gix_worktree::Stack,
+}

gix/src/worktree/mod.rs

@@ -145,7 +145,7 @@ pub mod excludes {
 
 ///
 pub mod attributes {
-    use crate::Worktree;
+    use crate::{AttributeStack, Worktree};
 
     /// The error returned by [`Worktree::attributes()`].
     #[derive(Debug, thiserror::Error)]
@@ -164,7 +164,7 @@ pub mod attributes {
         ///
         /// * `$XDG_CONFIG_HOME/…/ignore|attributes` if `core.excludesFile|attributesFile` is *not* set, otherwise use the configured file.
         /// * `$GIT_DIR/info/exclude|attributes` if present.
-        pub fn attributes(&self, overrides: Option<gix_ignore::Search>) -> Result<gix_worktree::Stack, Error> {
+        pub fn attributes(&self, overrides: Option<gix_ignore::Search>) -> Result<AttributeStack<'repo>, Error> {
             let index = self.index()?;
             Ok(self.parent.attributes(
                 &index,
@@ -175,7 +175,7 @@ pub mod attributes {
         }
 
         /// Like [attributes()][Self::attributes()], but without access to exclude/ignore information.
-        pub fn attributes_only(&self) -> Result<gix_worktree::Stack, Error> {
+        pub fn attributes_only(&self) -> Result<AttributeStack<'repo>, Error> {
             let index = self.index()?;
             self.parent
                 .attributes_only(