commit traversals on shallow clones are non-fatal by default (#364)

But we make it easy to detect if the traversal was shallow or not.

That way there will be no 'fail by default' issues in apps using
gitoxide when they encountered partial graph (at least as long as
they don't try to do anything with their parents).

Author: Byron

git-repository/src/id.rs

@@ -141,6 +141,8 @@ pub mod ancestors {
                     .sorting(sorting)
                     .parents(parents),
                 ),
+                is_shallow: None,
+                error_on_missing_commit: false,
             }
         }
     }
@@ -149,13 +151,50 @@ pub mod ancestors {
     pub struct Iter<'repo> {
         repo: &'repo crate::Repository,
         inner: Box<dyn Iterator<Item = Result<git_hash::ObjectId, git_traverse::commit::ancestors::Error>> + 'repo>,
+        error_on_missing_commit: bool,
+        // TODO: tests
+        /// After iteration this flag is true if the iteration was stopped prematurely due to missing parent commits.
+        /// Note that this flag won't be `Some` if any iteration error occours, which is the case if
+        /// [`error_on_missing_commit()`][Iter::error_on_missing_commit()] was called.
+        ///
+        /// This happens if a repository is a shallow clone.
+        /// Note that this value is `None` as long as the iteration isn't complete.
+        pub is_shallow: Option<bool>,
+    }
+
+    impl<'repo> Iter<'repo> {
+        // TODO: tests
+        /// Once invoked, the iteration will return an error if a commit cannot be found in the object database. This typicall happens
+        /// when operating on a shallow clone and thus is non-critical by default.
+        ///
+        /// Check the [`is_shallow`][Iter::is_shallow] field once the iteration ended otherwise to learn if a shallow commit graph
+        /// was encountered.
+        pub fn error_on_missing_commit(mut self) -> Self {
+            self.error_on_missing_commit = true;
+            self
+        }
     }
 
     impl<'repo> Iterator for Iter<'repo> {
         type Item = Result<Id<'repo>, git_traverse::commit::ancestors::Error>;
 
         fn next(&mut self) -> Option<Self::Item> {
-            self.inner.next().map(|res| res.map(|oid| oid.attach(self.repo)))
+            match self.inner.next() {
+                None => {
+                    self.is_shallow = Some(false);
+                    None
+                }
+                Some(Ok(oid)) => Some(Ok(oid.attach(self.repo))),
+                Some(Err(err @ git_traverse::commit::ancestors::Error::FindExisting { .. })) => {
+                    if self.error_on_missing_commit {
+                        Some(Err(err))
+                    } else {
+                        self.is_shallow = Some(true);
+                        None
+                    }
+                }
+                Some(Err(err)) => Some(Err(err)),
+            }
         }
     }
 }

git-repository/src/reference/iter.rs

@@ -18,17 +18,23 @@ pub struct Iter<'r> {
     repo: &'r crate::Repository,
 }
 
+impl<'r> Iter<'r> {
+    fn new(repo: &'r crate::Repository, platform: git_ref::file::iter::LooseThenPacked<'r, 'r>) -> Self {
+        Iter {
+            inner: platform,
+            peel: false,
+            repo,
+        }
+    }
+}
+
 impl<'r> Platform<'r> {
     /// Return an iterator over all references in the repository.
     ///
     /// Even broken or otherwise unparsible or inaccessible references are returned and have to be handled by the caller on a
     /// case by case basis.
     pub fn all(&self) -> Result<Iter<'_>, init::Error> {
-        Ok(Iter {
-            inner: self.platform.all()?,
-            peel: false,
-            repo: self.repo,
-        })
+        Ok(Iter::new(self.repo, self.platform.all()?))
     }
 
     /// Return an iterator over all references that match the given `prefix`.
@@ -37,47 +43,31 @@ impl<'r> Platform<'r> {
     // TODO: Create a custom `Path` type that enforces the requirements of git naturally, this type is surprising possibly on windows
     //       and when not using a trailing '/' to signal directories.
     pub fn prefixed(&self, prefix: impl AsRef<Path>) -> Result<Iter<'_>, init::Error> {
-        Ok(Iter {
-            inner: self.platform.prefixed(prefix)?,
-            peel: false,
-            repo: self.repo,
-        })
+        Ok(Iter::new(self.repo, self.platform.prefixed(prefix)?))
     }
 
     // TODO: tests
     /// Return an iterator over all references that are tags.
     ///
     /// They are all prefixed with `refs/tags`.
     pub fn tags(&self) -> Result<Iter<'_>, init::Error> {
-        Ok(Iter {
-            inner: self.platform.prefixed("refs/tags/")?,
-            peel: false,
-            repo: self.repo,
-        })
+        Ok(Iter::new(self.repo, self.platform.prefixed("refs/tags/")?))
     }
 
     // TODO: tests
     /// Return an iterator over all local branches.
     ///
     /// They are all prefixed with `refs/heads`.
     pub fn local_branches(&self) -> Result<Iter<'_>, init::Error> {
-        Ok(Iter {
-            inner: self.platform.prefixed("refs/heads/")?,
-            peel: false,
-            repo: self.repo,
-        })
+        Ok(Iter::new(self.repo, self.platform.prefixed("refs/heads/")?))
     }
 
     // TODO: tests
     /// Return an iterator over all remote branches.
     ///
     /// They are all prefixed with `refs/remotes`.
     pub fn remote_branches(&self) -> Result<Iter<'_>, init::Error> {
-        Ok(Iter {
-            inner: self.platform.prefixed("refs/remotes/")?,
-            peel: false,
-            repo: self.repo,
-        })
+        Ok(Iter::new(self.repo, self.platform.prefixed("refs/remotes/")?))
     }
 }