feat: add Repository::is_dirty()

The simplest way to learn if the repository is dirty or not.

Author: Byron

gix/src/status/mod.rs

@@ -83,6 +83,52 @@ impl Repository {
     }
 }
 
+///
+#[cfg(feature = "parallel")]
+pub mod is_dirty {
+    use crate::Repository;
+
+    /// The error returned by [Repository::is_dirty()].
+    #[derive(Debug, thiserror::Error)]
+    #[allow(missing_docs)]
+    pub enum Error {
+        #[error(transparent)]
+        StatusPlatform(#[from] crate::config::boolean::Error),
+        #[error(transparent)]
+        CreateStatusIterator(#[from] crate::status::index_worktree::iter::Error),
+    }
+
+    impl Repository {
+        /// Returns `true` if the repository is dirty.
+        /// This means it's changed in one of the following ways:
+        ///
+        /// * the index was changed in comparison to its working tree
+        /// * the working tree was changed in comparison to the index
+        /// * submodules are taken in consideration, along with their `ignore` and `isActive` configuration
+        ///
+        /// Note that *untracked files* do *not* affect this flag.
+        ///
+        /// ### Incomplete Implementation Warning
+        ///
+        /// Currently, this does not compute changes between the head and the index.
+        // TODO: use iterator which also tests for head->index changes.
+        pub fn is_dirty(&self) -> Result<bool, Error> {
+            let is_dirty = self
+                .status(gix_features::progress::Discard)?
+                .index_worktree_rewrites(None)
+                .index_worktree_submodules(crate::status::Submodule::AsConfigured { check_dirty: true })
+                .index_worktree_options_mut(|opts| {
+                    opts.dirwalk_options = None;
+                })
+                .into_index_worktree_iter(Vec::new())?
+                .take_while(Result::is_ok)
+                .next()
+                .is_some();
+            Ok(is_dirty)
+        }
+    }
+}
+
 mod platform;
 
 ///

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

@@ -10,6 +10,7 @@ git init -q module1
   git commit -q -m c1
   echo hello >> this
   git commit -q -am c2
+  touch untracked
 )
 
 git init submodule-head-changed

gix/tests/fixtures/make_submodules.sh

@@ -44,3 +44,45 @@ mod index_worktree {
         }
     }
 }
+
+mod is_dirty {
+    use crate::status::repo;
+
+    #[test]
+    fn various_changes_positive() -> crate::Result {
+        let repo = repo("modified-untracked-and-submodule-head-changed-and-modified")?;
+        assert!(repo.is_dirty()?, "The repository has various changes");
+        Ok(())
+    }
+
+    #[test]
+    fn submodule_changes_are_picked_up() -> crate::Result {
+        let repo = repo("submodule-head-changed")?;
+        assert!(repo.is_dirty()?, "head-changes are also discoverd");
+        Ok(())
+    }
+
+    #[test]
+    fn untracked_files_are_excluded() -> crate::Result {
+        let repo = repo("module1")?;
+        assert_eq!(
+            repo.status(gix::progress::Discard)?
+                .into_index_worktree_iter(Vec::new())?
+                .count(),
+            1,
+            "there is one untracked file"
+        );
+        assert!(
+            !repo.is_dirty()?,
+            "untracked files aren't taken into consideration, just like `git describe` which ignores them"
+        );
+        Ok(())
+    }
+
+    #[test]
+    fn no_changes() -> crate::Result {
+        let repo = repo("with-submodules")?;
+        assert!(!repo.is_dirty()?, "there are no changes");
+        Ok(())
+    }
+}