feat: provide Repository::find_fetch_remote() to obtain a remote just like git would.

Author: Byron

gix/src/remote/errors.rs

@@ -2,7 +2,7 @@
 pub mod find {
     use crate::{bstr::BString, config, remote};
 
-    /// The error returned by [`Repository::find_remote(…)`][crate::Repository::find_remote()].
+    /// The error returned by [`Repository::find_remote(…)`](crate::Repository::find_remote()).
     #[derive(Debug, thiserror::Error)]
     #[allow(missing_docs)]
     pub enum Error {
@@ -30,7 +30,7 @@ pub mod find {
     pub mod existing {
         use crate::bstr::BString;
 
-        /// The error returned by [`Repository::find_remote(…)`][crate::Repository::find_remote()].
+        /// The error returned by [`Repository::find_remote(…)`](crate::Repository::find_remote()).
         #[derive(Debug, thiserror::Error)]
         #[allow(missing_docs)]
         pub enum Error {
@@ -42,4 +42,23 @@ pub mod find {
             NotFound { name: BString },
         }
     }
+
+    ///
+    pub mod for_fetch {
+        /// The error returned by [`Repository::find_fetch_remote(…)`](crate::Repository::find_fetch_remote()).
+        #[derive(Debug, thiserror::Error)]
+        #[allow(missing_docs)]
+        pub enum Error {
+            #[error(transparent)]
+            FindExisting(#[from] super::existing::Error),
+            #[error(transparent)]
+            FindExistingReferences(#[from] crate::reference::find::existing::Error),
+            #[error("Could not initialize a URL remote")]
+            Init(#[from] crate::remote::init::Error),
+            #[error("remote name could not be parsed as URL")]
+            UrlParse(#[from] gix_url::parse::Error),
+            #[error("No configured remote could be found, or too many were available")]
+            ExactlyOneRemoteNotAvailable,
+        }
+    }
 }

gix/src/repository/remote.rs

@@ -28,7 +28,8 @@ impl crate::Repository {
         Remote::from_fetch_url(url, false, self)
     }
 
-    /// Find the remote with the given `name_or_url` or report an error, similar to [`try_find_remote(…)`][Self::try_find_remote()].
+    /// Find the configured remote with the given `name_or_url` or report an error,
+    /// similar to [`try_find_remote(…)`][Self::try_find_remote()].
     ///
     /// Note that we will obtain remotes only if we deem them [trustworthy][crate::open::Options::filter_config_section()].
     pub fn find_remote<'a>(&self, name_or_url: impl Into<&'a BStr>) -> Result<Remote<'_>, find::existing::Error> {
@@ -42,7 +43,7 @@ impl crate::Repository {
 
     /// Find the default remote as configured, or `None` if no such configuration could be found.
     ///
-    /// See [`remote_default_name()`][Self::remote_default_name()] for more information on the `direction` parameter.
+    /// See [`remote_default_name()`](Self::remote_default_name()) for more information on the `direction` parameter.
     pub fn find_default_remote(
         &self,
         direction: remote::Direction,
@@ -51,8 +52,8 @@ impl crate::Repository {
             .map(|name| self.find_remote(name.as_ref()))
     }
 
-    /// Find the remote with the given `name_or_url` or return `None` if it doesn't exist, for the purpose of fetching or pushing
-    /// data to a remote.
+    /// Find the configured remote with the given `name_or_url` or return `None` if it doesn't exist,
+    /// for the purpose of fetching or pushing data.
     ///
     /// There are various error kinds related to partial information or incorrectly formatted URLs or ref-specs.
     /// Also note that the created `Remote` may have neither fetch nor push ref-specs set at all.
@@ -65,6 +66,35 @@ impl crate::Repository {
         self.try_find_remote_inner(name_or_url, true)
     }
 
+    /// This method emulate what `git fetch <remote>` does in order to obtain a remote to fetch from.
+    ///
+    /// As such, with `name_or_url` being `Some`, it will:
+    ///
+    /// * use `name_or_url` verbatim if it is a URL, creating a new remote in memory as needed.
+    /// * find the named remote if `name_or_url` is a remote name
+    ///
+    /// If `name_or_url` is `None`:
+    ///
+    /// * use the current `HEAD` branch to find a configured remote
+    /// * fall back to either a generally configured remote or the only configured remote.
+    ///
+    /// Fail if no remote could be found despite all of the above.
+    pub fn find_fetch_remote(&self, name_or_url: Option<&BStr>) -> Result<Remote<'_>, find::for_fetch::Error> {
+        Ok(match name_or_url {
+            Some(name) => match self.try_find_remote(name).and_then(Result::ok) {
+                Some(remote) => remote,
+                None => self.remote_at(gix_url::parse(name)?)?,
+            },
+            None => self
+                .head()?
+                .into_remote(remote::Direction::Fetch)
+                .transpose()?
+                .map(Ok)
+                .or_else(|| self.find_default_remote(remote::Direction::Fetch))
+                .ok_or_else(|| find::for_fetch::Error::ExactlyOneRemoteNotAvailable)??,
+        })
+    }
+
     /// Similar to [`try_find_remote()`][Self::try_find_remote()], but removes a failure mode if rewritten URLs turn out to be invalid
     /// as it skips rewriting them.
     /// Use this in conjunction with [`Remote::rewrite_urls()`] to non-destructively apply the rules and keep the failed urls unchanged.

gix/tests/head/mod.rs

@@ -9,6 +9,11 @@ mod into_remote {
             repo.head()?.into_remote(gix::remote::Direction::Fetch).transpose()?,
             None
         );
+        assert_eq!(
+            repo.find_fetch_remote(None)?.name().expect("present").as_ref(),
+            "origin",
+            "we can fallback to the only available remote"
+        );
         Ok(())
     }
 
@@ -19,6 +24,11 @@ mod into_remote {
             repo.head()?.into_remote(gix::remote::Direction::Fetch).transpose()?,
             None
         );
+        assert_eq!(
+            repo.find_fetch_remote(None)?.name().expect("present").as_ref(),
+            "origin",
+            "we can fallback to the only available remote"
+        );
         Ok(())
     }
 }

gix/tests/reference/remote.rs

@@ -78,6 +78,13 @@ fn not_configured() -> crate::Result {
     assert_eq!(branch.remote_name(gix::remote::Direction::Fetch), None);
     assert_eq!(branch.remote(gix::remote::Direction::Fetch).transpose()?, None);
     assert_eq!(head.into_remote(gix::remote::Direction::Fetch).transpose()?, None);
+    assert!(
+        matches!(
+            repo.find_fetch_remote(None),
+            Err(gix::remote::find::for_fetch::Error::ExactlyOneRemoteNotAvailable)
+        ),
+        "there is no remote to be found"
+    );
 
     Ok(())
 }

gix/tests/repository/remote.rs

@@ -291,6 +291,46 @@ mod find_remote {
     }
 }
 
+mod find_fetch_remote {
+    use crate::remote;
+
+    #[test]
+    fn symbol_name() -> crate::Result {
+        let repo = remote::repo("clone-no-tags");
+        assert_eq!(
+            repo.find_fetch_remote(Some("origin".into()))?
+                .name()
+                .expect("set")
+                .as_bstr(),
+            "origin"
+        );
+        Ok(())
+    }
+
+    #[test]
+    fn urls() -> crate::Result {
+        let repo = remote::repo("clone-no-tags");
+        for url in [
+            "some-path",
+            "https://example.com/repo",
+            "other/path",
+            "ssh://host/ssh-aliased-repo",
+        ] {
+            let remote = repo.find_fetch_remote(Some(url.into()))?;
+            assert_eq!(remote.name(), None, "this remote is anonymous");
+            assert_eq!(
+                remote
+                    .url(gix::remote::Direction::Fetch)
+                    .expect("url is set")
+                    .to_bstring(),
+                url,
+                "if it's not a configured remote, we take it as URL"
+            );
+        }
+        Ok(())
+    }
+}
+
 mod find_default_remote {
 
     use crate::remote;