produce only a ref-map as it contains all data somebody would want. (#450)

It does more work as well, but it seems unnecessary to maintian a bigger
API surface and it might be key to turning this into a step-by-step
transition to fetching packs and updating local references.

Author: Byron

Diff for: git-repository/src/remote/connection/list_refs.rs

@@ -66,4 +66,4 @@ mod access {
 }
 
 ///
-pub mod list_refs;
+pub mod ref_map;

Diff for: git-repository/src/remote/connection/mod.rs

@@ -0,0 +1,114 @@
+use git_features::progress::Progress;
+use git_protocol::transport::client::Transport;
+
+use crate::remote::{connection::HandshakeWithRefs, fetch, Connection, Direction};
+
+/// The error returned by [`Connection::list_refs_to_map()`].
+#[derive(Debug, thiserror::Error)]
+#[allow(missing_docs)]
+pub enum Error {
+    #[error(transparent)]
+    Handshake(#[from] git_protocol::fetch::handshake::Error),
+    #[error(transparent)]
+    ListRefs(#[from] git_protocol::fetch::refs::Error),
+    #[error(transparent)]
+    Transport(#[from] git_protocol::transport::client::Error),
+    #[error(transparent)]
+    ConfigureCredentials(#[from] crate::config::credential_helpers::Error),
+    #[error(transparent)]
+    MappingValidation(#[from] git_refspec::match_group::validate::Error),
+}
+
+impl<'a, 'repo, T, P> Connection<'a, 'repo, T, P>
+where
+    T: Transport,
+    P: Progress,
+{
+    /// List all references on the remote that have been filtered through our remote's [`refspecs`][crate::Remote::refspecs()]
+    /// 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).
+    ///
+    /// Note that this doesn't fetch the objects mentioned in the tips nor does it make any change to underlying repository.
+    #[git_protocol::maybe_async::maybe_async]
+    pub async fn ref_map(mut self) -> Result<fetch::RefMap, Error> {
+        let res = self.ref_map_inner().await;
+        git_protocol::fetch::indicate_end_of_interaction(&mut self.transport).await?;
+        res
+    }
+
+    #[git_protocol::maybe_async::maybe_async]
+    async fn ref_map_inner(&mut self) -> Result<fetch::RefMap, Error> {
+        let remote = self.fetch_refs().await?;
+        let group = git_refspec::MatchGroup::from_fetch_specs(self.remote.fetch_specs.iter().map(|s| s.to_ref()));
+        let (res, fixes) = group
+            .match_remotes(remote.refs.iter().map(|r| {
+                let (full_ref_name, target, object) = r.unpack();
+                git_refspec::match_group::Item {
+                    full_ref_name,
+                    target,
+                    object,
+                }
+            }))
+            .validated()?;
+        let mappings = res.mappings;
+        let mappings = mappings
+            .into_iter()
+            .map(|m| fetch::Mapping {
+                remote: m
+                    .item_index
+                    .map(|idx| fetch::Source::Ref(remote.refs[idx].clone()))
+                    .unwrap_or_else(|| {
+                        fetch::Source::ObjectId(match m.lhs {
+                            git_refspec::match_group::SourceRef::ObjectId(id) => id,
+                            _ => unreachable!("no item index implies having an object id"),
+                        })
+                    }),
+                local: m.rhs.map(|c| c.into_owned()),
+                spec_index: m.spec_index,
+            })
+            .collect();
+        Ok(fetch::RefMap {
+            mappings,
+            fixes,
+            remote_refs: remote.refs,
+            handshake: remote.outcome,
+        })
+    }
+    #[git_protocol::maybe_async::maybe_async]
+    async fn fetch_refs(&mut self) -> Result<HandshakeWithRefs, Error> {
+        let mut credentials_storage;
+        let authenticate = match self.credentials.as_mut() {
+            Some(f) => f,
+            None => {
+                let url = self
+                    .remote
+                    .url(Direction::Fetch)
+                    .map(ToOwned::to_owned)
+                    .unwrap_or_else(|| {
+                        git_url::parse(self.transport.to_url().as_bytes().into())
+                            .expect("valid URL to be provided by transport")
+                    });
+                credentials_storage = self.configured_credentials(url)?;
+                &mut credentials_storage
+            }
+        };
+        let mut outcome =
+            git_protocol::fetch::handshake(&mut self.transport, authenticate, Vec::new(), &mut self.progress).await?;
+        let refs = match outcome.refs.take() {
+            Some(refs) => refs,
+            None => {
+                git_protocol::fetch::refs(
+                    &mut self.transport,
+                    outcome.server_protocol_version,
+                    &outcome.capabilities,
+                    |_a, _b, _c| Ok(git_protocol::fetch::delegate::LsRefsAction::Continue),
+                    &mut self.progress,
+                )
+                .await?
+            }
+        };
+        Ok(HandshakeWithRefs { outcome, refs })
+    }
+}

Diff for: git-repository/src/remote/connection/ref_map.rs

@@ -73,7 +73,7 @@ pub mod connect;
 #[cfg(any(feature = "async-network-client", feature = "blocking-network-client"))]
 mod connection;
 #[cfg(any(feature = "async-network-client", feature = "blocking-network-client"))]
-pub use connection::{list_refs, Connection};
+pub use connection::{ref_map, Connection};
 
 mod access;
 pub(crate) mod url;

Diff for: git-repository/src/remote/mod.rs

@@ -24,22 +24,20 @@ mod blocking_io {
             }
 
             let remote = repo.find_remote("origin")?;
-            {
-                let connection = remote.connect(Fetch, progress::Discard)?;
-                let refs = connection.list_refs()?;
-                assert_eq!(refs.len(), 14, "it gets all remote refs, independently of the refspec.");
-            }
+            let connection = remote.connect(Fetch, progress::Discard)?;
+            let map = connection.ref_map()?;
+            assert_eq!(
+                map.remote_refs.len(),
+                14,
+                "it gets all remote refs, independently of the refspec."
+            );
 
-            {
-                let connection = remote.connect(Fetch, progress::Discard)?;
-                let map = connection.list_refs_to_map()?;
-                assert_eq!(map.fixes.len(), 0);
-                assert_eq!(
-                    map.mappings.len(),
-                    11,
-                    "mappings are only a sub-set of all remotes due to refspec matching"
-                );
-            }
+            assert_eq!(map.fixes.len(), 0);
+            assert_eq!(
+                map.mappings.len(),
+                11,
+                "mappings are only a sub-set of all remotes due to refspec matching"
+            );
         }
         Ok(())
     }