feat: add Repository::attributes() and Worktree::attributes().

Author: Byron

crate-status.md

@@ -690,7 +690,7 @@ See its [README.md](https://github.com/Byron/gitoxide/blob/main/gix-lock/README.
        * [x] proper handling of worktree related refs
        * [ ] create, move, remove, and repair
        * [x] access exclude information
-       * [ ]  access attribute information
+       * [x] access attribute information
        * [x] respect `core.worktree` configuration
           - **deviation**
              * The delicate interplay between `GIT_COMMON_DIR` and `GIT_WORK_TREE` isn't implemented.

gix/src/attributes.rs

@@ -0,0 +1,9 @@
+/// The error returned by [`Repository::attributes()`].
+#[derive(Debug, thiserror::Error)]
+#[allow(missing_docs)]
+pub enum Error {
+    #[error(transparent)]
+    ConfigureAttributes(#[from] crate::config::attribute_stack::Error),
+    #[error(transparent)]
+    ConfigureExcludes(#[from] crate::config::exclude_stack::Error),
+}

gix/src/config/cache/access.rs

@@ -167,11 +167,13 @@ impl Cache {
             symlink: boolean(self, "core.symlinks", &Core::SYMLINKS, true)?,
         };
         Ok(gix_worktree::checkout::Options {
-            attributes: self.assemble_attribute_globals(
-                git_dir,
-                gix_worktree::cache::state::attributes::Source::IdMappingThenWorktree,
-                self.attributes,
-            )?,
+            attributes: self
+                .assemble_attribute_globals(
+                    git_dir,
+                    gix_worktree::cache::state::attributes::Source::IdMappingThenWorktree,
+                    self.attributes,
+                )?
+                .0,
             fs: capabilities,
             thread_limit,
             destination_is_initially_empty: false,
@@ -192,13 +194,29 @@ impl Cache {
         })
     }
 
+    pub(crate) fn assemble_exclude_globals(
+        &self,
+        git_dir: &std::path::Path,
+        overrides: Option<gix_ignore::Search>,
+        buf: &mut Vec<u8>,
+    ) -> Result<gix_worktree::cache::state::Ignore, config::exclude_stack::Error> {
+        let excludes_file = match self.excludes_file().transpose()? {
+            Some(user_path) => Some(user_path),
+            None => self.xdg_config_path("ignore")?,
+        };
+        Ok(gix_worktree::cache::state::Ignore::new(
+            overrides.unwrap_or_default(),
+            gix_ignore::Search::from_git_dir(git_dir, excludes_file, buf)?,
+            None,
+        ))
+    }
     // TODO: at least one test, maybe related to core.attributesFile configuration.
-    fn assemble_attribute_globals(
+    pub(crate) fn assemble_attribute_globals(
         &self,
         git_dir: &std::path::Path,
         source: gix_worktree::cache::state::attributes::Source,
         attributes: crate::open::permissions::Attributes,
-    ) -> Result<gix_worktree::cache::state::Attributes, config::attribute_stack::Error> {
+    ) -> Result<(gix_worktree::cache::state::Attributes, Vec<u8>), config::attribute_stack::Error> {
         let configured_or_user_attributes = match self
             .trusted_file_path("core", None, Core::ATTRIBUTES_FILE.name)
             .transpose()?
@@ -224,12 +242,13 @@ impl Cache {
         let info_attributes_path = git_dir.join("info").join("attributes");
         let mut buf = Vec::new();
         let mut collection = gix_attributes::search::MetadataCollection::default();
-        Ok(gix_worktree::cache::state::Attributes::new(
+        let res = gix_worktree::cache::state::Attributes::new(
             gix_attributes::Search::new_globals(attribute_files, &mut buf, &mut collection)?,
             Some(info_attributes_path),
             source,
             collection,
-        ))
+        );
+        Ok((res, buf))
     }
 
     pub(crate) fn xdg_config_path(

gix/src/config/mod.rs

@@ -118,6 +118,23 @@ pub mod checkout_options {
     }
 }
 
+///
+pub mod exclude_stack {
+    use std::path::PathBuf;
+
+    /// The error produced when setting up a stack to query `gitignore` information.
+    #[derive(Debug, thiserror::Error)]
+    #[allow(missing_docs)]
+    pub enum Error {
+        #[error("Could not read repository exclude")]
+        Io(#[from] std::io::Error),
+        #[error(transparent)]
+        EnvironmentPermission(#[from] gix_sec::permission::Error<PathBuf>),
+        #[error("The value for `core.excludesFile` could not be read from configuration")]
+        ExcludesFilePathInterpolation(#[from] gix_config::path::interpolate::Error),
+    }
+}
+
 ///
 pub mod attribute_stack {
     /// The error produced when setting up the attribute stack to query `gitattributes`.

gix/src/lib.rs

@@ -99,6 +99,9 @@ pub use hash::{oid, ObjectId};
 
 pub mod interrupt;
 
+///
+pub mod attributes;
+
 mod ext;
 ///
 pub mod prelude;
@@ -127,7 +130,7 @@ pub mod head;
 pub mod id;
 pub mod object;
 pub mod reference;
-pub mod repository;
+mod repository;
 pub mod tag;
 
 ///

gix/src/repository/attributes.rs

@@ -0,0 +1,47 @@
+//! exclude information
+use crate::Repository;
+
+impl Repository {
+    /// Configure a file-system cache for accessing git attributes *and* excludes on a per-path basis.
+    ///
+    /// Use `attribute_source` to specify where to read attributes from. Also note that exclude information will
+    /// always try to read `.gitignore` files from disk before trying to read it from the `index`.
+    ///
+    /// Note that no worktree is required for this to work, even though access to in-tree `.gitattributes` and `.gitignore` files
+    /// would require a non-empty `index` that represents a git tree.
+    ///
+    /// This takes into consideration all the usual repository configuration, namely:
+    ///
+    /// * `$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,
+        source: gix_worktree::cache::state::attributes::Source,
+        exclude_overrides: Option<gix_ignore::Search>,
+    ) -> Result<gix_worktree::Cache, crate::attributes::Error> {
+        let case = if self.config.ignore_case {
+            gix_glob::pattern::Case::Fold
+        } else {
+            gix_glob::pattern::Case::Sensitive
+        };
+        let (attributes, mut buf) =
+            self.config
+                .assemble_attribute_globals(self.git_dir(), source, self.options.permissions.attributes)?;
+        let ignore = self
+            .config
+            .assemble_exclude_globals(self.git_dir(), exclude_overrides, &mut buf)?;
+        let state = gix_worktree::cache::State::AttributesAndIgnoreStack { attributes, ignore };
+        let attribute_list = state.id_mappings_from_index(index, index.path_backing(), case);
+        Ok(gix_worktree::Cache::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,
+        ))
+    }
+}

gix/src/repository/excludes.rs

@@ -1,19 +1,5 @@
 //! exclude information
-use crate::Repository;
-use std::path::PathBuf;
-
-/// The error returned by [`Repository::excludes()`].
-#[derive(Debug, thiserror::Error)]
-#[allow(missing_docs)]
-pub enum Error {
-    #[error("Could not read repository exclude")]
-    Io(#[from] std::io::Error),
-    #[error(transparent)]
-    EnvironmentPermission(#[from] gix_sec::permission::Error<PathBuf>),
-    #[error("The value for `core.excludesFile` could not be read from configuration")]
-    ExcludesFilePathInterpolation(#[from] gix_config::path::interpolate::Error),
-}
-
+use crate::{config, Repository};
 impl Repository {
     /// Configure a file-system cache checking if files below the repository are excluded.
     ///
@@ -24,28 +10,26 @@ impl Repository {
     ///
     /// * `$XDG_CONFIG_HOME/…/ignore` if `core.excludesFile` is *not* set, otherwise use the configured file.
     /// * `$GIT_DIR/info/exclude` if present.
+    ///
+    /// When only excludes are desired, this is the most efficient way to obtain them. Otherwise use
+    /// [`Repository::attributes()`] for accessing both attributes and excludes.
     // 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 excludes(
         &self,
         index: &gix_index::State,
         overrides: Option<gix_ignore::Search>,
-    ) -> Result<gix_worktree::Cache, Error> {
+    ) -> Result<gix_worktree::Cache, config::exclude_stack::Error> {
         let case = if self.config.ignore_case {
             gix_glob::pattern::Case::Fold
         } else {
             gix_glob::pattern::Case::Sensitive
         };
         let mut buf = Vec::with_capacity(512);
-        let excludes_file = match self.config.excludes_file().transpose()? {
-            Some(user_path) => Some(user_path),
-            None => self.config.xdg_config_path("ignore")?,
-        };
-        let state = gix_worktree::cache::State::IgnoreStack(gix_worktree::cache::state::Ignore::new(
-            overrides.unwrap_or_default(),
-            gix_ignore::Search::from_git_dir(self.git_dir(), excludes_file, &mut buf)?,
-            None,
-        ));
+        let ignore = self
+            .config
+            .assemble_exclude_globals(self.git_dir(), overrides, &mut buf)?;
+        let state = gix_worktree::cache::State::IgnoreStack(ignore);
         let attribute_list = state.id_mappings_from_index(index, index.path_backing(), case);
         Ok(gix_worktree::Cache::new(
             // this is alright as we don't cause mutation of that directory, it's virtual.

gix/src/repository/mod.rs

@@ -19,9 +19,10 @@ impl crate::Repository {
     }
 }
 
+mod attributes;
 mod cache;
 mod config;
-pub mod excludes;
+mod excludes;
 pub(crate) mod identity;
 mod impls;
 mod init;

gix/src/worktree/mod.rs

@@ -103,7 +103,7 @@ pub mod excludes {
         #[error(transparent)]
         OpenIndex(#[from] crate::worktree::open_index::Error),
         #[error(transparent)]
-        CreateCache(#[from] crate::repository::excludes::Error),
+        CreateCache(#[from] crate::config::exclude_stack::Error),
     }
 
     impl<'repo> crate::Worktree<'repo> {
@@ -113,9 +113,45 @@ pub mod excludes {
         ///
         /// * `$XDG_CONFIG_HOME/…/ignore` if `core.excludesFile` is *not* set, otherwise use the configured file.
         /// * `$GIT_DIR/info/exclude` if present.
+        ///
+        /// When only excludes are desired, this is the most efficient way to obtain them. Otherwise use
+        /// [`Worktree::attributes()`][crate::Worktree::attributes()] for accessing both attributes and excludes.
         pub fn excludes(&self, overrides: Option<gix_ignore::Search>) -> Result<gix_worktree::Cache, Error> {
             let index = self.index()?;
             Ok(self.parent.excludes(&index, overrides)?)
         }
     }
 }
+
+///
+pub mod attributes {
+    /// The error returned by [`Worktree::attributes()`][crate::Worktree::attributes()].
+    #[derive(Debug, thiserror::Error)]
+    #[allow(missing_docs)]
+    pub enum Error {
+        #[error(transparent)]
+        OpenIndex(#[from] crate::worktree::open_index::Error),
+        #[error(transparent)]
+        CreateCache(#[from] crate::attributes::Error),
+    }
+
+    impl<'repo> crate::Worktree<'repo> {
+        /// Configure a file-system cache checking if files below the repository are excluded or for querying their attributes.
+        ///
+        /// Use `attribute_source` to specify where to read attributes from. Also note that exclude information will
+        /// always try to read `.gitignore` files from disk before trying to read it from the `index`.
+        ///
+        /// This takes into consideration all the usual repository configuration, namely:
+        ///
+        /// * `$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,
+            source: gix_worktree::cache::state::attributes::Source,
+            overrides: Option<gix_ignore::Search>,
+        ) -> Result<gix_worktree::Cache, Error> {
+            let index = self.index()?;
+            Ok(self.parent.attributes(&index, source, overrides)?)
+        }
+    }
+}