Implement object checkout in PrepareCheckout

gix/src/clone/checkout.rs

@@ -5,6 +5,7 @@ use crate::{clone::PrepareCheckout, Repository};
 pub mod main_worktree {
     use std::{path::PathBuf, sync::atomic::AtomicBool};
 
+    use crate::ext::{ObjectIdExt, ReferenceExt};
     use crate::{clone::PrepareCheckout, Progress, Repository};
 
     /// The error returned by [`PrepareCheckout::main_worktree()`].
@@ -60,6 +61,54 @@ pub mod main_worktree {
 
     /// Modification
     impl PrepareCheckout {
+        /// Set the `name` of the reference to check out, instead of the remote `HEAD`.
+        /// If `None`, the `HEAD` will be used, which is the default.
+        ///
+        /// Note that `name` should be a partial name like `main` or `feat/one`, but can be a full ref name.
+        /// If a branch on the remote matches, it will automatically be retrieved even without a refspec.
+        pub fn with_ref_name<'a, Name, E>(self, ref_name: Option<Name>) -> Result<PrepareCheckout, Error>
+        where
+            Name: TryInto<&'a gix_ref::PartialNameRef, Error = E>,
+            gix_ref::file::find::Error: std::convert::From<E>,
+        {
+            let repo = self
+                .repo
+                .as_ref()
+                .expect("BUG: this method may only be called until it is successful");
+
+            let reference = ref_name
+                .map(|ref_name| repo.try_find_reference(ref_name))
+                .transpose()
+                .map_err(|e| Error::FindHead(crate::reference::find::existing::Error::Find(e)))?
+                .flatten()
+                .map(|r| r.detach());
+
+            self.with_ref(reference)
+        }
+
+        /// Set the reference to checkout from the tree.
+        pub fn with_ref<'a>(mut self, ref_val: Option<gix_ref::Reference>) -> Result<PrepareCheckout, Error> {
+            let repo = self
+                .repo
+                .as_ref()
+                .expect("BUG: this method may only be called until it is successful");
+
+            self.checkout_object = ref_val
+                .map(|r| r.attach(repo))
+                .map(|r| r.into_fully_peeled_id())
+                .transpose()?
+                .map(|r| r.inner);
+
+            Ok(self)
+        }
+
+        /// Set the reference to checkout from the tree.
+        pub fn with_object_id(mut self, object_id: Option<crate::ObjectId>) -> PrepareCheckout {
+            self.checkout_object = object_id;
+
+            self
+        }
+
         /// Checkout the main worktree, determining how many threads to use by looking at `checkout.workers`, defaulting to using
         /// on thread per logical core.
         ///
@@ -97,8 +146,8 @@ pub mod main_worktree {
                 git_dir: repo.git_dir().to_owned(),
             })?;
 
-            let root_tree_id = match &self.ref_name {
-                Some(reference_val) => Some(repo.find_reference(reference_val)?.peel_to_id_in_place()?),
+            let root_tree_id = match self.checkout_object {
+                Some(reference_val) => Some(reference_val.attach(repo)),
                 None => repo.head()?.try_peel_to_id_in_place()?,
             };
 

gix/src/clone/fetch/mod.rs

@@ -232,8 +232,8 @@ impl PrepareFetch {
         Ok((
             crate::clone::PrepareCheckout {
                 repo: repo.into(),
-                ref_name: self.ref_name.clone(),
-            },
+                checkout_object: None,
+            }.with_ref_name(self.ref_name.as_ref()).expect("BUG: Ref not found in repo after fetching!"),
             fetch_outcome,
         ))
     }

gix/src/clone/mod.rs

@@ -138,8 +138,8 @@ impl PrepareFetch {
 pub struct PrepareCheckout {
     /// A freshly initialized repository which is owned by us, or `None` if it was successfully checked out.
     pub(self) repo: Option<crate::Repository>,
-    /// The name of the reference to check out. If `None`, the reference pointed to by `HEAD` will be checked out.
-    pub(self) ref_name: Option<gix_ref::PartialName>,
+    /// The object that will be checked out, or `None` if checking out HEAD.
+    pub(self) checkout_object: Option<gix_hash::ObjectId>,
 }
 
 // This module encapsulates functionality that works with both feature toggles. Can be combined with `fetch`