feat: Add Submodule::status() method.

That way it's possible to obtain submodule status information,
with enough information to implement `git status`-like commands.

Author: Byron

gix-submodule/src/config.rs

@@ -4,8 +4,6 @@ use bstr::{BStr, BString, ByteSlice};
 #[derive(Default, Debug, Clone, Copy, Ord, PartialOrd, Eq, PartialEq, Hash)]
 pub enum Ignore {
     /// Submodule changes won't be considered at all, which is the fastest option.
-    ///
-    /// Note that changes to the submodule hash in the superproject will still be observable.
     All,
     /// Ignore any changes to the submodule working tree, only show committed differences between the `HEAD` of the submodule
     /// compared to the recorded commit in the superproject.

gix/src/status/platform.rs

@@ -5,8 +5,9 @@ impl<'repo, Progress> Platform<'repo, Progress>
 where
     Progress: gix_features::progress::Progress,
 {
-    /// Call `cb` on dirwalk options if these are set (which is the default). The directory walk is used to find
-    /// untracked files or ignored files.
+    /// Call `cb` on dirwalk options if these are set (which is the default when created through [`Repository::status()`](crate::Repository::status())).
+    /// The directory walk is used to find untracked files or ignored files.
+    ///
     /// `cb` will be able to run builder-methods on the passed dirwalk options.
     pub fn dirwalk_options(mut self, cb: impl FnOnce(crate::dirwalk::Options) -> crate::dirwalk::Options) -> Self {
         if let Some(opts) = self.index_worktree_options.dirwalk_options.take() {

gix/src/submodule/mod.rs

@@ -275,6 +275,174 @@ impl<'repo> Submodule<'repo> {
     }
 }
 
+///
+#[cfg(all(feature = "status", feature = "parallel"))]
+pub mod status {
+    use super::{head_id, index_id, open, Status};
+    use crate::Submodule;
+    use gix_submodule::config;
+
+    /// The error returned by [Submodule::status()].
+    #[derive(Debug, thiserror::Error)]
+    #[allow(missing_docs)]
+    pub enum Error {
+        #[error(transparent)]
+        State(#[from] config::path::Error),
+        #[error(transparent)]
+        HeadId(#[from] head_id::Error),
+        #[error(transparent)]
+        IndexId(#[from] index_id::Error),
+        #[error(transparent)]
+        OpenRepository(#[from] open::Error),
+        #[error(transparent)]
+        IgnoreConfiguration(#[from] config::Error),
+        #[error(transparent)]
+        StatusPlatform(#[from] crate::config::boolean::Error),
+        #[error(transparent)]
+        Status(#[from] crate::status::index_worktree::iter::Error),
+    }
+
+    impl<'repo> Submodule<'repo> {
+        /// Return the status of the submodule.
+        ///
+        /// Use `ignore` to control the portion of the submodule status to ignore. It can be obtained from
+        /// submodule configuration using the [`ignore()`](Submodule::ignore()) method.
+        /// If `check_dirty` is `true`, the computation will stop once the first in a ladder operations
+        /// ordered from cheap to expensive shows that the submodule is dirty.
+        /// Thus, submodules that are clean will still impose the complete set of computation, as given.
+        #[doc(alias = "submodule_status", alias = "git2")]
+        pub fn status(
+            &self,
+            ignore: config::Ignore,
+            check_dirty: bool,
+        ) -> Result<crate::submodule::status::types::Status, Error> {
+            self.status_opts(ignore, check_dirty, &mut |s| s)
+        }
+        /// Return the status of the submodule, just like [`status`](Self::status), but allows to adjust options
+        /// for more control over how the status is performed.
+        ///
+        /// Use `&mut std::convert::identity` for `adjust_options` if no specific options are desired.
+        /// A reason to change them might be to enable sorting to enjoy deterministic order of changes.
+        ///
+        /// The status allows to easily determine if a submodule [has changes](Status::is_dirty).
+        #[doc(alias = "submodule_status", alias = "git2")]
+        pub fn status_opts(
+            &self,
+            ignore: config::Ignore,
+            check_dirty: bool,
+            adjust_options: &mut dyn for<'a> FnMut(
+                crate::status::Platform<'a, gix_features::progress::Discard>,
+            )
+                -> crate::status::Platform<'a, gix_features::progress::Discard>,
+        ) -> Result<Status, Error> {
+            let mut state = self.state()?;
+            if ignore == config::Ignore::All {
+                return Ok(Status {
+                    state,
+                    ..Default::default()
+                });
+            }
+
+            let index_id = self.index_id()?;
+            if !state.repository_exists {
+                return Ok(Status {
+                    state,
+                    index_id,
+                    ..Default::default()
+                });
+            }
+            let sm_repo = match self.open()? {
+                None => {
+                    state.repository_exists = false;
+                    return Ok(Status {
+                        state,
+                        index_id,
+                        ..Default::default()
+                    });
+                }
+                Some(repo) => repo,
+            };
+
+            let checked_out_head_id = sm_repo.head_id().ok().map(crate::Id::detach);
+            let mut status = Status {
+                state,
+                index_id,
+                checked_out_head_id,
+                ..Default::default()
+            };
+            if ignore == config::Ignore::Dirty || check_dirty && status.is_dirty() == Some(true) {
+                return Ok(status);
+            }
+
+            status.changes = Some(
+                adjust_options(sm_repo.status(gix_features::progress::Discard)?)
+                    // TODO: Run the full status, including tree->index once available.
+                    .index_worktree_options_mut(|opts| {
+                        assert!(opts.dirwalk_options.is_some(), "BUG: it's supposed to be the default");
+                        if ignore == config::Ignore::Untracked {
+                            opts.dirwalk_options = None;
+                        }
+                    })
+                    .into_index_worktree_iter(Vec::new())?
+                    .filter_map(Result::ok)
+                    .collect(),
+            );
+
+            Ok(status)
+        }
+    }
+
+    impl Status {
+        /// Return `Some(true)` if the submodule status could be determined sufficiently and
+        /// if there are changes that would render this submodule dirty.
+        ///
+        /// Return `Some(false)` if the submodule status could be determined and it has no changes
+        /// at all.
+        ///
+        /// Return `None` if the repository clone or the worktree are missing entirely, which would leave
+        /// it to the caller to determine if that's considered dirty or not.
+        pub fn is_dirty(&self) -> Option<bool> {
+            if !self.state.worktree_checkout && !self.state.repository_exists {
+                return None;
+            }
+            let is_dirty =
+                self.checked_out_head_id != self.index_id || self.changes.as_ref().map_or(false, |c| !c.is_empty());
+            Some(is_dirty)
+        }
+    }
+
+    pub(super) mod types {
+        use crate::submodule::State;
+
+        /// A simplified status of the Submodule.
+        ///
+        /// As opposed to the similar-sounding [`State`], it is more exhaustive and potentially expensive to compute,
+        /// particularly for submodules without changes.
+        ///
+        /// It's produced by [Submodule::status()](crate::Submodule::status()).
+        #[derive(Default, Clone, PartialEq, Debug)]
+        pub struct Status {
+            /// The cheapest part of the status that is always performed, to learn if the repository is cloned
+            /// and if there is a worktree checkout.
+            pub state: State,
+            /// The commit at which the submodule is supposed to be according to the super-project's index.
+            /// `None` means the computation wasn't performed, or the submodule didn't exist in the super-project's index anymore.
+            pub index_id: Option<gix_hash::ObjectId>,
+            /// The commit-id of the `HEAD` at which the submodule is currently checked out.
+            /// `None` if the computation wasn't performed as it was skipped early, or if no repository was available or
+            /// if the HEAD could not be obtained or wasn't born.
+            pub checked_out_head_id: Option<gix_hash::ObjectId>,
+            /// The set of changes obtained from running something akin to `git status` in the submodule working tree.
+            ///
+            /// `None` if the computation wasn't performed as the computation was skipped early, or if no working tree was
+            /// available or repository was available.
+            pub changes: Option<Vec<crate::status::index_worktree::iter::Item>>,
+        }
+    }
+}
+#[cfg(all(feature = "status", feature = "parallel"))]
+pub use status::types::Status;
+
 /// A summary of the state of all parts forming a submodule, which allows to answer various questions about it.
 ///
 /// Note that expensive questions about its presence in the `HEAD` or the `index` are left to the caller.

gix/tests/fixtures/generated-archives/make_submodules.tar.xz

@@ -12,6 +12,36 @@ git init -q module1
   git commit -q -am c2
 )
 
+git init submodule-head-changed
+(cd submodule-head-changed
+  git submodule add ../module1 m1
+  git commit -m "add submodule"
+
+  cd m1 && git checkout @~1
+)
+
+git init modified-and-untracked
+(cd modified-and-untracked
+  git submodule add ../module1 m1
+  git commit -m "add submodule"
+
+  (cd m1
+    echo change >> this
+    touch new
+  )
+)
+
+git init submodule-head-changed-and-modified
+(cd submodule-head-changed-and-modified
+  git submodule add ../module1 m1
+  git commit -m "add submodule"
+
+  (cd m1
+    git checkout @~1
+    echo change >> this
+  )
+)
+
 git init with-submodules
 (cd with-submodules
   mkdir dir