sketch API for obtaining a reflist filtered by refspecs (#450)

Author: Byron

git-repository/src/remote/connection/list_refs.rs

@@ -1,7 +1,7 @@
 use git_features::progress::Progress;
 use git_protocol::transport::client::Transport;
 
-use crate::remote::{connection::HandshakeWithRefs, Connection, Direction};
+use crate::remote::{connection::HandshakeWithRefs, fetch, Connection, Direction};
 
 mod error {
     #[derive(Debug, thiserror::Error)]
@@ -33,6 +33,13 @@ where
         Ok(res.refs)
     }
 
+    /// A mapping showing the objects available in refs matching our ref-specs on the remote side, along with their destination
+    /// ref locally, if set and if there are no conflicts.
+    #[git_protocol::maybe_async::maybe_async]
+    pub async fn ref_mapping(self) -> Result<Vec<fetch::Mapping>, Error> {
+        todo!()
+    }
+
     #[git_protocol::maybe_async::maybe_async]
     async fn fetch_refs(&mut self) -> Result<HandshakeWithRefs, Error> {
         let mut credentials_storage;

git-repository/src/remote/mod.rs

@@ -25,6 +25,20 @@ pub use errors::find;
 ///
 pub mod init;
 
+///
+#[cfg(any(feature = "async-network-client", feature = "blocking-network-client"))]
+pub mod fetch {
+    use crate::bstr::BString;
+
+    /// A mapping between a single remote reference and its advertised objects to a local destination which may or may not exist.
+    pub struct Mapping {
+        /// The reference on the remote side, along with information about the objects they point to as advertised by the server.
+        pub remote: git_protocol::fetch::Ref,
+        /// The local tracking reference to update after fetching the object visible via `remote`.
+        pub local: Option<BString>,
+    }
+}
+
 ///
 #[cfg(any(feature = "async-network-client", feature = "blocking-network-client"))]
 pub mod connect;