feat!: describe usees commitgraph.

With it it can leverage the commitgraph data structure would would be more prominent
on server-side applications, presumably.

Author: Byron

gix-commitgraph/tests/fixtures/create_fixtures.sh

@@ -94,7 +94,8 @@ impl<'a> Display for Format<'a> {
     }
 }
 
-type Flags = u32;
+/// A bit-field which keeps track of which commit is reachable by one of 32 candidates names.
+pub type Flags = u32;
 const MAX_CANDIDATES: usize = std::mem::size_of::<Flags>() * 8;
 
 /// The options required to call [`describe()`][function::describe()].
@@ -129,14 +130,11 @@ impl<'name> Default for Options<'name> {
 /// The error returned by the [`describe()`][function::describe()] function.
 #[derive(Debug, thiserror::Error)]
 #[allow(missing_docs)]
-pub enum Error<E>
-where
-    E: std::error::Error + Send + Sync + 'static,
-{
-    #[error("Commit {} could not be found during graph traversal", .oid.to_hex())]
-    Find {
+pub enum Error {
+    #[error("The parents of commit {} could not be added to graph during traversal", oid.to_hex())]
+    InsertParentsToGraph {
         #[source]
-        err: Option<E>,
+        err: crate::graph::insert_parents::Error,
         oid: gix_hash::ObjectId,
     },
     #[error("A commit could not be decoded during traversal")]
@@ -148,32 +146,26 @@ pub(crate) mod function {
 
     use bstr::BStr;
     use gix_hash::oid;
-    use gix_hashtable::{hash_map, HashMap};
-    use gix_object::CommitRefIter;
 
     use super::{Error, Outcome};
     use crate::describe::{CommitTime, Flags, Options, MAX_CANDIDATES};
-    use crate::PriorityQueue;
+    use crate::{Graph, PriorityQueue};
 
-    /// Given a `commit` id, traverse the commit graph and collect candidate names from the `name_by_oid` mapping to produce
+    /// Given a `commit` id, traverse the commit `graph` and collect candidate names from the `name_by_oid` mapping to produce
     /// an `Outcome`, which converted [`into_format()`][Outcome::into_format()] will produce a typical `git describe` string.
     ///
     /// Note that the `name_by_oid` map is returned in the [`Outcome`], which can be forcefully returned even if there was no matching
     /// candidate by setting `fallback_to_oid` to true.
-    pub fn describe<'name, Find, E>(
+    pub fn describe<'name>(
         commit: &oid,
-        mut find: Find,
+        graph: &mut Graph<'_, Flags>,
         Options {
             name_by_oid,
             mut max_candidates,
             fallback_to_oid,
             first_parent,
         }: Options<'name>,
-    ) -> Result<Option<Outcome<'name>>, Error<E>>
-    where
-        Find: for<'b> FnMut(&oid, &'b mut Vec<u8>) -> Result<Option<CommitRefIter<'b>>, E>,
-        E: std::error::Error + Send + Sync + 'static,
-    {
+    ) -> Result<Option<Outcome<'name>>, Error> {
         max_candidates = max_candidates.min(MAX_CANDIDATES);
         if let Some(name) = name_by_oid.get(commit) {
             return Ok(Some(Outcome {
@@ -199,15 +191,12 @@ pub(crate) mod function {
             };
         }
 
-        let mut buf = Vec::new();
-        let mut parent_buf = Vec::new();
-
         let mut queue = PriorityQueue::from_iter(Some((u32::MAX, commit.to_owned())));
         let mut candidates = Vec::new();
         let mut commits_seen = 0;
         let mut gave_up_on_commit = None;
-        let mut seen = HashMap::<gix_hash::ObjectId, Flags>::default();
-        seen.insert(commit.to_owned(), 0u32);
+        graph.clear();
+        graph.insert(commit.to_owned(), 0u32);
 
         while let Some(commit) = queue.pop() {
             commits_seen += 1;
@@ -220,15 +209,15 @@ pub(crate) mod function {
                         identity_bit,
                         order: candidates.len(),
                     });
-                    let flags = seen.get_mut(&commit).expect("inserted");
+                    let flags = graph.get_mut(&commit).expect("inserted");
                     *flags |= identity_bit;
                     *flags
                 } else {
                     gave_up_on_commit = Some(commit);
                     break;
                 }
             } else {
-                seen[&commit]
+                graph[&commit]
             };
 
             for candidate in candidates
@@ -261,16 +250,7 @@ pub(crate) mod function {
                 }
             }
 
-            parents_by_date_onto_queue_and_track_names(
-                &mut find,
-                &mut buf,
-                &mut parent_buf,
-                &mut queue,
-                &mut seen,
-                &commit,
-                flags,
-                first_parent,
-            )?;
+            parents_by_date_onto_queue_and_track_names(graph, &mut queue, commit, flags, first_parent)?;
         }
 
         if candidates.is_empty() {
@@ -300,11 +280,8 @@ pub(crate) mod function {
 
         commits_seen += finish_depth_computation(
             queue,
-            find,
+            graph,
             candidates.first_mut().expect("at least one candidate"),
-            seen,
-            buf,
-            parent_buf,
             first_parent,
         )?;
 
@@ -317,105 +294,49 @@ pub(crate) mod function {
         }))
     }
 
-    #[allow(clippy::too_many_arguments)]
-    fn parents_by_date_onto_queue_and_track_names<Find, E>(
-        find: &mut Find,
-        buf: &mut Vec<u8>,
-        parent_buf: &mut Vec<u8>,
+    fn parents_by_date_onto_queue_and_track_names(
+        graph: &mut Graph<'_, Flags>,
         queue: &mut PriorityQueue<CommitTime, gix_hash::ObjectId>,
-        seen: &mut HashMap<gix_hash::ObjectId, Flags>,
-        commit: &gix_hash::oid,
+        commit: gix_hash::ObjectId,
         commit_flags: Flags,
         first_parent: bool,
-    ) -> Result<(), Error<E>>
-    where
-        Find: for<'b> FnMut(&oid, &'b mut Vec<u8>) -> Result<Option<CommitRefIter<'b>>, E>,
-        E: std::error::Error + Send + Sync + 'static,
-    {
-        let commit_iter = find(commit, buf)
-            .map_err(|err| Error::Find {
-                err: Some(err),
-                oid: commit.to_owned(),
-            })?
-            .ok_or_else(|| Error::Find {
-                err: None,
-                oid: commit.to_owned(),
-            })?;
-        for token in commit_iter {
-            match token {
-                Ok(gix_object::commit::ref_iter::Token::Tree { .. }) => continue,
-                Ok(gix_object::commit::ref_iter::Token::Parent { id: parent_id }) => match seen.entry(parent_id) {
-                    hash_map::Entry::Vacant(entry) => {
-                        let parent = match find(&parent_id, parent_buf).map_err(|err| Error::Find {
-                            err: Some(err),
-                            oid: commit.to_owned(),
-                        })? {
-                            Some(p) => p,
-                            None => continue, // skip missing objects, they don't exist.
-                        };
-
-                        let parent_commit_date = parent
-                            .committer()
-                            .map(|committer| committer.time.seconds_since_unix_epoch)
-                            .unwrap_or_default();
-
-                        entry.insert(commit_flags);
-                        queue.insert(parent_commit_date, parent_id);
-                    }
-                    hash_map::Entry::Occupied(mut entry) => {
-                        *entry.get_mut() |= commit_flags;
-                    }
+    ) -> Result<(), Error> {
+        graph
+            .insert_parents(
+                &commit,
+                |parent_id, parent_commit_date| {
+                    queue.insert(parent_commit_date as u32, parent_id);
+                    commit_flags
                 },
-                Ok(_unused_token) => break,
-                Err(err) => return Err(err.into()),
-            }
-            if first_parent {
-                break;
-            }
-        }
-
+                |_parent_id, flags| *flags |= commit_flags,
+                first_parent,
+            )
+            .map_err(|err| Error::InsertParentsToGraph { err, oid: commit })?;
         Ok(())
     }
 
-    #[allow(clippy::too_many_arguments)]
-    fn finish_depth_computation<'name, Find, E>(
+    fn finish_depth_computation(
         mut queue: PriorityQueue<CommitTime, gix_hash::ObjectId>,
-        mut find: Find,
-        best_candidate: &mut Candidate<'name>,
-        mut seen: HashMap<gix_hash::ObjectId, Flags>,
-        mut buf: Vec<u8>,
-        mut parent_buf: Vec<u8>,
+        graph: &mut Graph<'_, Flags>,
+        best_candidate: &mut Candidate<'_>,
         first_parent: bool,
-    ) -> Result<u32, Error<E>>
-    where
-        Find: for<'b> FnMut(&oid, &'b mut Vec<u8>) -> Result<Option<CommitRefIter<'b>>, E>,
-        E: std::error::Error + Send + Sync + 'static,
-    {
+    ) -> Result<u32, Error> {
         let mut commits_seen = 0;
         while let Some(commit) = queue.pop() {
             commits_seen += 1;
-            let flags = seen[&commit];
+            let flags = graph[&commit];
             if (flags & best_candidate.identity_bit) == best_candidate.identity_bit {
                 if queue
                     .iter_random()
-                    .all(|id| (seen[id] & best_candidate.identity_bit) == best_candidate.identity_bit)
+                    .all(|id| (graph[id] & best_candidate.identity_bit) == best_candidate.identity_bit)
                 {
                     break;
                 }
             } else {
                 best_candidate.commits_in_its_future += 1;
             }
 
-            parents_by_date_onto_queue_and_track_names(
-                &mut find,
-                &mut buf,
-                &mut parent_buf,
-                &mut queue,
-                &mut seen,
-                &commit,
-                flags,
-                first_parent,
-            )?;
+            parents_by_date_onto_queue_and_track_names(graph, &mut queue, commit, flags, first_parent)?;
         }
         Ok(commits_seen)
     }
@@ -431,4 +352,5 @@ pub(crate) mod function {
     }
 }
 
+/// The timestamp for the creation date of a commit in seconds since unix epoch.
 type CommitTime = u32;

gix-revision/src/describe.rs

@@ -13,26 +13,29 @@ mod format;
 fn run_test(
     transform_odb: impl FnOnce(gix_odb::Handle) -> gix_odb::Handle,
     options: impl Fn(gix_hash::ObjectId) -> gix_revision::describe::Options<'static>,
-    run_assertions: impl Fn(
-        Result<Option<Outcome<'static>>, Error<gix_odb::store::find::Error>>,
-        gix_hash::ObjectId,
-    ) -> crate::Result,
+    run_assertions: impl Fn(Result<Option<Outcome<'static>>, Error>, gix_hash::ObjectId) -> crate::Result,
 ) -> crate::Result {
     let store = odb_at(".");
     let store = transform_odb(store);
     let commit_id = hex_to_id("01ec18a3ebf2855708ad3c9d244306bc1fae3e9b");
-    run_assertions(
-        gix_revision::describe(
-            &commit_id,
+    for use_commitgraph in [false, true] {
+        let cache = use_commitgraph
+            .then(|| gix_commitgraph::Graph::from_info_dir(store.store_ref().path().join("info")).ok())
+            .flatten();
+        let mut graph = gix_revision::Graph::new(
             |id, buf| {
                 store
                     .try_find(id, buf)
                     .map(|r| r.and_then(|d| d.try_into_commit_iter()))
             },
-            options(commit_id),
-        ),
-        commit_id,
-    )
+            cache,
+        );
+        run_assertions(
+            gix_revision::describe(&commit_id, &mut graph, options(commit_id)),
+            commit_id,
+        )?;
+    }
+    Ok(())
 }
 
 #[test]

gix-revision/tests/describe/mod.rs

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:51c255848776de0f426ffb8858ce44f0b09ab3ac2075628b594f520cf86a55ba
-size 13124
+oid sha256:7e3e6e069d37db14bb8138eaf7f9d7fade2db6c9985a065da1bbf0684678c961
+size 12452

gix-revision/tests/fixtures/generated-archives/make_repo_with_branches.tar.xz

@@ -21,5 +21,8 @@ git commit -q --allow-empty -m c5
 git tag at-c5
 git merge branch1 -m m1b1
 
+git commit-graph write --no-progress --reachable
+git repack -adq
+
 git clone --depth 1 file://$PWD shallow-1-clone
 git clone --depth 2 file://$PWD shallow-2-clone