wire up the ref-map sub-command. (#450)

Without implementation though, which is mainly display.

Author: Byron

Diff for: README.md

@@ -48,6 +48,7 @@ Please see _'Development Status'_ for a listing of all crates and their capabili
         * [x] **previous-branches** - list all previously checked out branches, powered by the ref-log.
     * **remote**    
         * [x] **refs** - list all references available on the remote based on the current remote configuration.
+        * [x] **ref-map** - show how remote references relate to their local tracking branches as mapped by refspecs.
     * **credential**
         * [x] **fill/approve/reject** - The same as `git credential`, but implemented in Rust, calling helpers only when from trusted configuration.
     * **free** - no git repository necessary

Diff for: crate-status.md

@@ -14,7 +14,6 @@
 ### git-object
 * *decode (zero-copy)* borrowed objects
     * [x] commit
-      * [x] parse the title, body, and provide a title summary.
       * [ ] parse [trailers](https://git-scm.com/docs/git-interpret-trailers#_description) 
     * [x] tree
 * encode owned objects

Diff for: gitoxide-core/src/repository/remote.rs

@@ -1,5 +1,5 @@
 #[cfg(any(feature = "blocking-client", feature = "async-client"))]
-mod net {
+mod refs_impl {
     use anyhow::bail;
     use git_repository as git;
     use git_repository::protocol::fetch;
@@ -11,6 +11,11 @@ mod net {
 
         pub const PROGRESS_RANGE: std::ops::RangeInclusive<u8> = 1..=2;
 
+        pub enum Kind {
+            Remote,
+            Tracking,
+        }
+
         pub struct Context {
             pub format: OutputFormat,
             pub name: Option<String>,
@@ -23,6 +28,7 @@ mod net {
     #[git::protocol::maybe_async::maybe_async]
     pub async fn refs_fn(
         repo: git::Repository,
+        _kind: refs::Kind,
         mut progress: impl git::Progress,
         out: impl std::io::Write,
         refs::Context { format, name, url }: refs::Context,
@@ -44,17 +50,17 @@ mod net {
                 .context("Remote didn't have a URL to connect to")?
                 .to_bstring()
         ));
-        let refs = remote
+        let map = remote
             .connect(git::remote::Direction::Fetch, progress)
             .await?
-            .list_refs()
+            .ref_map()
             .await?;
 
         match format {
-            OutputFormat::Human => drop(print(out, &refs)),
+            OutputFormat::Human => drop(print(out, &map.remote_refs)),
             #[cfg(feature = "serde1")]
             OutputFormat::Json => {
-                serde_json::to_writer_pretty(out, &refs.into_iter().map(JsonRef::from).collect::<Vec<_>>())?
+                serde_json::to_writer_pretty(out, &map.remote_refs.into_iter().map(JsonRef::from).collect::<Vec<_>>())?
             }
         };
         Ok(())
@@ -137,4 +143,4 @@ mod net {
     }
 }
 #[cfg(any(feature = "blocking-client", feature = "async-client"))]
-pub use net::{refs, refs_fn as refs, JsonRef};
+pub use refs_impl::{refs, refs_fn as refs, JsonRef};

Diff for: src/plumbing/main.rs

@@ -122,7 +122,11 @@ pub fn main() -> Result<()> {
         #[cfg_attr(feature = "small", allow(unused_variables))]
         Subcommands::Remote(remote::Platform { name, url, cmd }) => match cmd {
             #[cfg(any(feature = "gitoxide-core-async-client", feature = "gitoxide-core-blocking-client"))]
-            remote::Subcommands::Refs => {
+            remote::Subcommands::Refs | remote::Subcommands::RefMap => {
+                let kind = match cmd {
+                    remote::Subcommands::Refs => core::repository::remote::refs::Kind::Remote,
+                    remote::Subcommands::RefMap => core::repository::remote::refs::Kind::Tracking,
+                };
                 #[cfg(feature = "gitoxide-core-blocking-client")]
                 {
                     prepare_and_run(
@@ -134,6 +138,7 @@ pub fn main() -> Result<()> {
                         move |progress, out, _err| {
                             core::repository::remote::refs(
                                 repository(Mode::LenientWithGitInstallConfig)?,
+                                kind,
                                 progress,
                                 out,
                                 core::repository::remote::refs::Context { name, url, format },
@@ -149,7 +154,8 @@ pub fn main() -> Result<()> {
                         Some(core::repository::remote::refs::PROGRESS_RANGE),
                     );
                     futures_lite::future::block_on(core::repository::remote::refs(
-                        repository(Mode::Lenient)?,
+                        repository(Mode::LenientWithGitInstallConfig)?,
+                        kind,
                         progress,
                         std::io::stdout(),
                         core::repository::remote::refs::Context { name, url, format },

Diff for: src/plumbing/options.rs

@@ -131,9 +131,12 @@ pub mod remote {
     #[derive(Debug, clap::Subcommand)]
     #[clap(visible_alias = "remotes")]
     pub enum Subcommands {
-        /// Print all references available on the remote
+        /// Print all references available on the remote.
         #[cfg(any(feature = "gitoxide-core-async-client", feature = "gitoxide-core-blocking-client"))]
         Refs,
+        /// Print all references available on the remote as filtered through ref-specs.
+        #[cfg(any(feature = "gitoxide-core-async-client", feature = "gitoxide-core-blocking-client"))]
+        RefMap,
     }
 }