feat: describing commits can now be done with conditional dirty-suffix using commit::describe::Resolution::format_with_dirty_suffix()

Author: Byron

gix/src/commit.rs

@@ -40,11 +40,32 @@ pub mod describe {
     }
 
     impl<'repo> Resolution<'repo> {
-        /// Turn this instance into something displayable
+        /// Turn this instance into something displayable.
         pub fn format(self) -> Result<gix_revision::describe::Format<'static>, Error> {
             let prefix = self.id.shorten()?;
             Ok(self.outcome.into_format(prefix.hex_len()))
         }
+
+        /// Turn this instance into something displayable, possibly with dirty-suffix.
+        ///
+        /// If `dirty_suffix` is `Some(suffix)`, a possibly expensive [dirty check](crate::Repository::is_dirty()) will be
+        /// performed so that the `suffix` is appended to the output. If it is `None`, no check will be performed and
+        /// there will be no suffix.
+        /// Note that obtaining the dirty-state of the repository can be expensive.
+        #[cfg(all(feature = "status", feature = "parallel"))]
+        pub fn format_with_dirty_suffix(
+            self,
+            dirty_suffix: impl Into<Option<String>>,
+        ) -> Result<gix_revision::describe::Format<'static>, Error> {
+            let prefix = self.id.shorten()?;
+            let mut dirty_suffix = dirty_suffix.into();
+            if dirty_suffix.is_some() && !self.id.repo.is_dirty()? {
+                dirty_suffix.take();
+            }
+            let mut format = self.outcome.into_format(prefix.hex_len());
+            format.dirty_suffix = dirty_suffix;
+            Ok(format)
+        }
     }
 
     /// The error returned by [`try_format()`][Platform::try_format()].
@@ -59,6 +80,9 @@ pub mod describe {
         RefIter(#[from] crate::reference::iter::Error),
         #[error(transparent)]
         RefIterInit(#[from] crate::reference::iter::init::Error),
+        #[error(transparent)]
+        #[cfg(all(feature = "status", feature = "parallel"))]
+        DetermineIsDirty(#[from] crate::status::is_dirty::Error),
     }
 
     /// A selector to choose what kind of references should contribute to names.
@@ -179,9 +203,7 @@ pub mod describe {
         }
 
         /// Try to find a name for the configured commit id using all prior configuration, returning `Some(describe::Format)`
-        /// if one was found.
-        ///
-        /// Note that there will always be `Some(format)`
+        /// if one was found, or `None` if that wasn't the case.
         pub fn try_format(&self) -> Result<Option<gix_revision::describe::Format<'static>>, Error> {
             self.try_resolve()?.map(Resolution::format).transpose()
         }
@@ -193,10 +215,9 @@ pub mod describe {
         ///
         /// # Performance
         ///
-        /// It is greatly recommended to [assure an object cache is set][crate::Repository::object_cache_size_if_unset()]
+        /// It is greatly recommended to [assure an object cache is set](crate::Repository::object_cache_size_if_unset())
         /// to save ~40% of time.
         pub fn try_resolve(&self) -> Result<Option<Resolution<'repo>>, Error> {
-            // TODO: dirty suffix with respective dirty-detection
             let mut graph = gix_revwalk::Graph::new(
                 &self.repo.objects,
                 gix_commitgraph::Graph::from_info_dir(self.repo.objects.store_ref().path().join("info").as_ref()).ok(),
@@ -218,7 +239,7 @@ pub mod describe {
             }))
         }
 
-        /// Like [`try_format()`][Platform::try_format()], but turns `id_as_fallback()` on to always produce a format.
+        /// Like [`try_format()`](Self::try_format()), but turns `id_as_fallback()` on to always produce a format.
         pub fn format(&mut self) -> Result<gix_revision::describe::Format<'static>, Error> {
             self.id_as_fallback = true;
             Ok(self.try_format()?.expect("BUG: fallback must always produce a format"))

gix/tests/commit/mod.rs

@@ -4,6 +4,48 @@ mod describe {
 
     use crate::named_repo;
 
+    #[cfg(all(feature = "status", feature = "parallel"))]
+    mod with_dirty_suffix {
+        use crate::util::named_subrepo_opts;
+        use gix::commit::describe::SelectRef;
+
+        #[test]
+        fn dirty_suffix_applies_automatically_if_dirty() -> crate::Result {
+            let repo = named_subrepo_opts(
+                "make_submodules.sh",
+                "submodule-head-changed",
+                gix::open::Options::isolated(),
+            )?;
+
+            let actual = repo
+                .head_commit()?
+                .describe()
+                .names(SelectRef::AllRefs)
+                .try_resolve()?
+                .expect("resolution")
+                .format_with_dirty_suffix("dirty".to_owned())?
+                .to_string();
+            assert_eq!(actual, "main-dirty");
+            Ok(())
+        }
+
+        #[test]
+        fn dirty_suffix_does_not_apply_if_not_dirty() -> crate::Result {
+            let repo = named_subrepo_opts("make_submodules.sh", "module1", gix::open::Options::isolated())?;
+
+            let actual = repo
+                .head_commit()?
+                .describe()
+                .names(SelectRef::AllRefs)
+                .try_resolve()?
+                .expect("resolution")
+                .format_with_dirty_suffix("dirty".to_owned())?
+                .to_string();
+            assert_eq!(actual, "main");
+            Ok(())
+        }
+    }
+
     #[test]
     fn tags_are_sorted_by_date_and_lexicographically() -> crate::Result {
         let repo = named_repo("make_commit_describe_multiple_tags.sh")?;