feat: add PrepareFetch::with_ref_name() to control which ref is checked out.

Author: Byron

gix/src/clone/access.rs

@@ -11,7 +11,7 @@ impl PrepareFetch {
     ///
     /// It can also be used to configure additional options, like those for fetching tags. Note that
     /// [`with_fetch_tags()`](crate::Remote::with_fetch_tags()) should be called here to configure the clone as desired.
-    /// Otherwise a clone is configured to be complete and fetches all tags, not only those reachable from all branches.
+    /// Otherwise, a clone is configured to be complete and fetches all tags, not only those reachable from all branches.
     pub fn configure_remote(
         mut self,
         f: impl FnMut(crate::Remote<'_>) -> Result<crate::Remote<'_>, Box<dyn std::error::Error + Send + Sync>> + 'static,
@@ -42,6 +42,19 @@ impl PrepareFetch {
         self.config_overrides = values.into_iter().map(Into::into).collect();
         self
     }
+
+    /// 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>(mut self, name: Option<Name>) -> Result<Self, E>
+    where
+        Name: TryInto<&'a gix_ref::PartialNameRef, Error = E>,
+    {
+        self.ref_name = name.map(TryInto::try_into).transpose()?.map(ToOwned::to_owned);
+        Ok(self)
+    }
 }
 
 /// Consumption

gix/src/clone/checkout.rs

@@ -5,8 +5,6 @@ use crate::{clone::PrepareCheckout, Repository};
 pub mod main_worktree {
     use std::{path::PathBuf, sync::atomic::AtomicBool};
 
-    use gix_ref::bstr::BStr;
-
     use crate::{clone::PrepareCheckout, Progress, Repository};
 
     /// The error returned by [`PrepareCheckout::main_worktree()`].
@@ -66,7 +64,7 @@ pub mod main_worktree {
         /// on thread per logical core.
         ///
         /// Note that this is a no-op if the remote was empty, leaving this repository empty as well. This can be validated by checking
-        /// if the `head()` of the returned repository is not unborn.
+        /// if the `head()` of the returned repository is *not* unborn.
         pub fn main_worktree<P>(
             &mut self,
             mut progress: P,
@@ -76,29 +74,13 @@ pub mod main_worktree {
             P: gix_features::progress::NestedProgress,
             P::SubProgress: gix_features::progress::NestedProgress + 'static,
         {
-            self.main_worktree_inner(&mut progress, should_interrupt, None)
-        }
-
-        /// Checkout the a worktree, determining how many threads to use by looking at `checkout.workers`, defaulting to using
-        /// on thread per logical core.
-        pub fn worktree<P>(
-            &mut self,
-            mut progress: P,
-            should_interrupt: &AtomicBool,
-            reference: Option<&BStr>,
-        ) -> Result<(Repository, gix_worktree_state::checkout::Outcome), Error>
-        where
-            P: gix_features::progress::NestedProgress,
-            P::SubProgress: gix_features::progress::NestedProgress + 'static,
-        {
-            self.main_worktree_inner(&mut progress, should_interrupt, reference)
+            self.main_worktree_inner(&mut progress, should_interrupt)
         }
 
         fn main_worktree_inner(
             &mut self,
             progress: &mut dyn gix_features::progress::DynNestedProgress,
             should_interrupt: &AtomicBool,
-            reference: Option<&BStr>,
         ) -> Result<(Repository, gix_worktree_state::checkout::Outcome), Error> {
             let _span = gix_trace::coarse!("gix::clone::PrepareCheckout::main_worktree()");
             let repo = self
@@ -109,7 +91,7 @@ pub mod main_worktree {
                 git_dir: repo.git_dir().to_owned(),
             })?;
 
-            let root_tree_id = match reference {
+            let root_tree_id = match &self.ref_name {
                 Some(reference_val) => Some(repo.find_reference(reference_val)?.peel_to_id_in_place()?),
                 None => repo.head()?.try_peel_to_id_in_place()?,
             };

gix/src/clone/fetch/mod.rs

@@ -1,3 +1,5 @@
+use crate::bstr::BString;
+use crate::bstr::ByteSlice;
 use crate::clone::PrepareFetch;
 
 /// The error returned by [`PrepareFetch::fetch_only()`].
@@ -35,6 +37,13 @@ pub enum Error {
     },
     #[error("Failed to update HEAD with values from remote")]
     HeadUpdate(#[from] crate::reference::edit::Error),
+    #[error("The remote didn't have any ref that matched '{}'", wanted.as_ref().as_bstr())]
+    RefNameMissing { wanted: gix_ref::PartialName },
+    #[error("The remote has {} refs for '{}', try to use a specific name: {}", candidates.len(), wanted.as_ref().as_bstr(), candidates.iter().filter_map(|n| n.to_str().ok()).collect::<Vec<_>>().join(", "))]
+    RefNameAmbiguous {
+        wanted: gix_ref::PartialName,
+        candidates: Vec<BString>,
+    },
 }
 
 /// Modification
@@ -117,7 +126,7 @@ impl PrepareFetch {
             remote = remote.with_fetch_tags(fetch_tags);
         }
 
-        // Add HEAD after the remote was written to config, we need it to know what to checkout later, and assure
+        // Add HEAD after the remote was written to config, we need it to know what to check out later, and assure
         // the ref that HEAD points to is present no matter what.
         let head_refspec = gix_refspec::parse(
             format!("HEAD:refs/remotes/{remote_name}/HEAD").as_str().into(),
@@ -136,10 +145,22 @@ impl PrepareFetch {
                     if !opts.extra_refspecs.contains(&head_refspec) {
                         opts.extra_refspecs.push(head_refspec)
                     }
+                    if let Some(ref_name) = &self.ref_name {
+                        opts.extra_refspecs.push(
+                            gix_refspec::parse(ref_name.as_ref().as_bstr(), gix_refspec::parse::Operation::Fetch)
+                                .expect("partial names are valid refspecs")
+                                .to_owned(),
+                        );
+                    }
                     opts
                 })
                 .await?
         };
+
+        // Assure problems with custom branch names fail early, not after getting the pack or during negotiation.
+        if let Some(ref_name) = &self.ref_name {
+            util::find_custom_refname(pending_pack.ref_map(), ref_name)?;
+        }
         if pending_pack.ref_map().object_hash != repo.object_hash() {
             unimplemented!("configure repository to expect a different object hash as advertised by the server")
         }
@@ -160,9 +181,10 @@ impl PrepareFetch {
         util::append_config_to_repo_config(repo, config);
         util::update_head(
             repo,
-            &outcome.ref_map.remote_refs,
+            &outcome.ref_map,
             reflog_message.as_ref(),
             remote_name.as_ref(),
+            self.ref_name.as_ref(),
         )?;
 
         Ok((self.repo.take().expect("still present"), outcome))
@@ -180,7 +202,13 @@ impl PrepareFetch {
         P::SubProgress: 'static,
     {
         let (repo, fetch_outcome) = self.fetch_only(progress, should_interrupt)?;
-        Ok((crate::clone::PrepareCheckout { repo: repo.into() }, fetch_outcome))
+        Ok((
+            crate::clone::PrepareCheckout {
+                repo: repo.into(),
+                ref_name: self.ref_name.clone(),
+            },
+            fetch_outcome,
+        ))
     }
 }
 

gix/src/clone/fetch/util.rs

@@ -2,7 +2,7 @@ use std::{borrow::Cow, io::Write};
 
 use gix_ref::{
     transaction::{LogChange, RefLog},
-    FullNameRef,
+    FullNameRef, PartialName,
 };
 
 use super::Error;
@@ -60,35 +60,40 @@ pub fn append_config_to_repo_config(repo: &mut Repository, config: gix_config::F
 
 /// HEAD cannot be written by means of refspec by design, so we have to do it manually here. Also create the pointed-to ref
 /// if we have to, as it might not have been naturally included in the ref-specs.
+/// Lastly, use `ref_name` if it was provided instead, and let `HEAD` point to it.
 pub fn update_head(
     repo: &mut Repository,
-    remote_refs: &[gix_protocol::handshake::Ref],
+    ref_map: &crate::remote::fetch::RefMap,
     reflog_message: &BStr,
     remote_name: &BStr,
+    ref_name: Option<&PartialName>,
 ) -> Result<(), Error> {
     use gix_ref::{
         transaction::{PreviousValue, RefEdit},
         Target,
     };
-    let (head_peeled_id, head_ref) = match remote_refs.iter().find_map(|r| {
-        Some(match r {
-            gix_protocol::handshake::Ref::Symbolic {
-                full_ref_name,
-                target,
-                tag: _,
-                object,
-            } if full_ref_name == "HEAD" => (Some(object.as_ref()), Some(target)),
-            gix_protocol::handshake::Ref::Direct { full_ref_name, object } if full_ref_name == "HEAD" => {
-                (Some(object.as_ref()), None)
-            }
-            gix_protocol::handshake::Ref::Unborn { full_ref_name, target } if full_ref_name == "HEAD" => {
-                (None, Some(target))
-            }
-            _ => return None,
-        })
-    }) {
-        Some(t) => t,
-        None => return Ok(()),
+    let head_info = match ref_name {
+        Some(ref_name) => Some(find_custom_refname(ref_map, ref_name)?),
+        None => ref_map.remote_refs.iter().find_map(|r| {
+            Some(match r {
+                gix_protocol::handshake::Ref::Symbolic {
+                    full_ref_name,
+                    target,
+                    tag: _,
+                    object,
+                } if full_ref_name == "HEAD" => (Some(object.as_ref()), Some(target.as_bstr())),
+                gix_protocol::handshake::Ref::Direct { full_ref_name, object } if full_ref_name == "HEAD" => {
+                    (Some(object.as_ref()), None)
+                }
+                gix_protocol::handshake::Ref::Unborn { full_ref_name, target } if full_ref_name == "HEAD" => {
+                    (None, Some(target.as_bstr()))
+                }
+                _ => return None,
+            })
+        }),
+    };
+    let Some((head_peeled_id, head_ref)) = head_info else {
+        return Ok(());
     };
 
     let head: gix_ref::FullName = "HEAD".try_into().expect("valid");
@@ -178,7 +183,55 @@ pub fn update_head(
     Ok(())
 }
 
-/// Setup the remote configuration for `branch` so that it points to itself, but on the remote, if and only if currently
+pub(super) fn find_custom_refname<'a>(
+    ref_map: &'a crate::remote::fetch::RefMap,
+    ref_name: &PartialName,
+) -> Result<(Option<&'a gix_hash::oid>, Option<&'a BStr>), Error> {
+    let group = gix_refspec::MatchGroup::from_fetch_specs(Some(
+        gix_refspec::parse(ref_name.as_ref().as_bstr(), gix_refspec::parse::Operation::Fetch)
+            .expect("partial names are valid refs"),
+    ));
+    // TODO: to fix ambiguity, implement priority system
+    let filtered_items: Vec<_> = ref_map
+        .mappings
+        .iter()
+        .filter_map(|m| {
+            m.remote
+                .as_name()
+                .and_then(|name| m.remote.as_id().map(|id| (name, id)))
+        })
+        .map(|(full_ref_name, target)| gix_refspec::match_group::Item {
+            full_ref_name,
+            target,
+            object: None,
+        })
+        .collect();
+    let res = group.match_remotes(filtered_items.iter().copied());
+    match res.mappings.len() {
+        0 => Err(Error::RefNameMissing {
+            wanted: ref_name.clone(),
+        }),
+        1 => {
+            let item = filtered_items[res.mappings[0]
+                .item_index
+                .expect("we map by name only and have no object-id in refspec")];
+            Ok((Some(item.target), Some(item.full_ref_name)))
+        }
+        _ => Err(Error::RefNameAmbiguous {
+            wanted: ref_name.clone(),
+            candidates: res
+                .mappings
+                .iter()
+                .filter_map(|m| match m.lhs {
+                    gix_refspec::match_group::SourceRef::FullName(name) => Some(name.to_owned()),
+                    gix_refspec::match_group::SourceRef::ObjectId(_) => None,
+                })
+                .collect(),
+        }),
+    }
+}
+
+/// Set up the remote configuration for `branch` so that it points to itself, but on the remote, if and only if currently
 /// saved refspecs are able to match it.
 /// For that we reload the remote of `remote_name` and use its `ref_specs` for match.
 fn setup_branch_config(

gix/src/clone/mod.rs

@@ -34,6 +34,9 @@ pub struct PrepareFetch {
     /// How to handle shallow clones
     #[cfg_attr(not(feature = "blocking-network-client"), allow(dead_code))]
     shallow: remote::fetch::Shallow,
+    /// The name of the reference to fetch. If `None`, the reference pointed to by `HEAD` will be checked out.
+    #[cfg_attr(not(feature = "blocking-network-client"), allow(dead_code))]
+    ref_name: Option<gix_ref::PartialName>,
 }
 
 /// The error returned by [`PrepareFetch::new()`].
@@ -132,6 +135,7 @@ impl PrepareFetch {
             #[cfg(any(feature = "async-network-client", feature = "blocking-network-client"))]
             configure_connection: None,
             shallow: remote::fetch::Shallow::NoChange,
+            ref_name: None,
         })
     }
 }
@@ -140,9 +144,12 @@ impl PrepareFetch {
 /// the fetched repository will be dropped.
 #[must_use]
 #[cfg(feature = "worktree-mutation")]
+#[derive(Debug)]
 pub struct PrepareCheckout {
     /// A freshly initialized repository which is owned by us, or `None` if it was handed to the user
     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>,
 }
 
 // This module encapsulates functionality that works with both feature toggles. Can be combined with `fetch`

gix/src/remote/connection/fetch/negotiate.rs

@@ -38,7 +38,7 @@ pub(crate) enum Action {
     SkipToRefUpdate,
     /// We can't know for sure if fetching *is not* needed, so we go ahead and negotiate.
     MustNegotiate {
-        /// Each `ref_map.mapping` has a slot here which is `true` if we have the object the remote ref points to locally.
+        /// Each `ref_map.mapping` has a slot here which is `true` if we have the object the remote ref points to, locally.
         remote_ref_target_known: Vec<bool>,
     },
 }
@@ -221,7 +221,7 @@ pub(crate) fn add_wants(
     shallow: &fetch::Shallow,
     mapping_is_ignored: impl Fn(&fetch::Mapping) -> bool,
 ) {
-    // When using shallow, we can't exclude `wants` as the remote won't send anything then. Thus we have to resend everything
+    // When using shallow, we can't exclude `wants` as the remote won't send anything then. Thus, we have to resend everything
     // we have as want instead to get exactly the same graph, but possibly deepened.
     let is_shallow = !matches!(shallow, fetch::Shallow::NoChange);
     let wants = ref_map

gix/src/remote/connection/fetch/receive_pack.rs

@@ -114,7 +114,7 @@ where
         gix_protocol::fetch::Response::check_required_features(protocol_version, &fetch_features)?;
         let sideband_all = fetch_features.iter().any(|(n, _)| *n == "sideband-all");
         let mut arguments = gix_protocol::fetch::Arguments::new(protocol_version, fetch_features, con.trace);
-        if matches!(con.remote.fetch_tags, crate::remote::fetch::Tags::Included) {
+        if matches!(con.remote.fetch_tags, fetch::Tags::Included) {
             if !arguments.can_use_include_tag() {
                 return Err(Error::MissingServerFeature {
                     feature: "include-tag",

gix/src/remote/connection/ref_map.rs

@@ -79,14 +79,14 @@ where
     /// for _fetching_.
     ///
     /// This comes in the form of all matching tips on the remote and the object they point to, along with
-    /// with the local tracking branch of these tips (if available).
+    /// the local tracking branch of these tips (if available).
     ///
     /// Note that this doesn't fetch the objects mentioned in the tips nor does it make any change to underlying repository.
     ///
     /// # Consumption
     ///
-    /// Due to management of the transport, it's cleanest to only use it for a single interaction. Thus it's consumed along with
-    /// the connection.
+    /// Due to management of the transport, it's cleanest to only use it for a single interaction. Thus, it's consumed
+    /// along with the connection.
     ///
     /// ### Configuration
     ///