feat: Add Reference::remote_tracking_ref_name() and *::remote_ref_name().

These methods mirror their respective `Repository::branch_*` prefixed versions.

Author: Byron

gix/src/reference/remote.rs

@@ -1,28 +1,47 @@
+use crate::repository::{branch_remote_ref_name, branch_remote_tracking_ref_name};
 use crate::{remote, Reference};
+use gix_ref::FullNameRef;
+use std::borrow::Cow;
 
 /// Remotes
 impl<'repo> Reference<'repo> {
     /// Find the name of our remote for `direction` as configured in `branch.<name>.remote|pushRemote` respectively.
-    /// If `Some(<name>)` it can be used in [`Repository::find_remote(…)`][crate::Repository::find_remote()], or if `None` then
-    /// [`Repository::remote_default_name()`][crate::Repository::remote_default_name()] could be used in its place.
-    ///
     /// Return `None` if no remote is configured.
     ///
-    /// # Note
-    ///
-    /// - it's recommended to use the [`remote(…)`][Self::remote()] method as it will configure the remote with additional
-    ///   information.
-    /// - `branch.<name>.pushRemote` falls back to `branch.<name>.remote`.
+    /// See also [`Repository::branch_remote_name()`](crate::Repository::branch_remote_name()) for more details.
     pub fn remote_name(&self, direction: remote::Direction) -> Option<remote::Name<'repo>> {
         self.repo.branch_remote_name(self.name().shorten(), direction)
     }
 
-    /// Like [`branch_remote(…)`](crate::Repository::branch_remote()), but automatically provides the reference name
-    /// for configuration lookup.
+    /// Find the remote along with all configuration associated with it suitable for handling this reference.
+    ///
+    /// See also [`Repository::branch_remote()`](crate::Repository::branch_remote()) for more details.
     pub fn remote(
         &self,
         direction: remote::Direction,
     ) -> Option<Result<crate::Remote<'repo>, remote::find::existing::Error>> {
         self.repo.branch_remote(self.name().shorten(), direction)
     }
+
+    /// Return the name of this reference on the remote side.
+    ///
+    /// See [`Repository::branch_remote_ref_name()`](crate::Repository::branch_remote_ref_name()) for details.
+    #[doc(alias = "upstream", alias = "git2")]
+    pub fn remote_ref_name(
+        &self,
+        direction: remote::Direction,
+    ) -> Option<Result<Cow<'_, FullNameRef>, branch_remote_ref_name::Error>> {
+        self.repo.branch_remote_ref_name(self.name(), direction)
+    }
+
+    /// Return the name of the reference that tracks this reference on the remote side.
+    ///
+    /// See [`Repository::branch_remote_tracking_ref_name()`](crate::Repository::branch_remote_tracking_ref_name()) for details.
+    #[doc(alias = "upstream", alias = "git2")]
+    pub fn remote_tracking_ref_name(
+        &self,
+        direction: remote::Direction,
+    ) -> Option<Result<Cow<'_, FullNameRef>, branch_remote_tracking_ref_name::Error>> {
+        self.repo.branch_remote_tracking_ref_name(self.name(), direction)
+    }
 }

gix/src/repository/config/mod.rs

@@ -228,6 +228,8 @@ mod branch {
         /// The value is also fast to retrieve compared to its tracking branch.
         /// Also note that a [remote::Direction] isn't used here as Git only supports (and requires) configuring
         /// the remote to fetch from, not the one to push to.
+        ///
+        /// See also [`Reference::remote_ref_name()`](crate::Reference::remote_ref_name()).
         #[doc(alias = "branch_upstream_name", alias = "git2")]
         pub fn branch_remote_ref_name(
             &self,
@@ -295,6 +297,8 @@ mod branch {
         ///
         /// Note that if there is an ambiguity, that is if `name` maps to multiple tracking branches, the first matching mapping
         /// is returned, according to the order in which the fetch or push refspecs occour in the configuration file.
+        ///
+        /// See also [`Reference::remote_tracking_ref_name()`](crate::Reference::remote_tracking_ref_name()).
         #[doc(alias = "branch_upstream_name", alias = "git2")]
         pub fn branch_remote_tracking_ref_name(
             &self,
@@ -326,7 +330,7 @@ mod branch {
         /// * if `direction` is [remote::Direction::Push], the push remote will be queried by means of `branch.<short_name>.pushRemote`
         ///   or `remote.pushDefault` as fallback.
         ///
-        /// See also [`Reference::remote_name()`][crate::Reference::remote_name()] for a more typesafe version
+        /// See also [`Reference::remote_name()`](crate::Reference::remote_name()) for a more typesafe version
         /// to be used when a `Reference` is available.
         ///
         /// `short_branch_name` can typically be obtained by [shortening a full branch name](FullNameRef::shorten()).
@@ -352,6 +356,8 @@ mod branch {
         /// Like [`branch_remote_name(…)`](Self::branch_remote_name()), but returns a [Remote](crate::Remote).
         /// `short_branch_name` is the name to use for looking up `branch.<short_branch_name>.*` values in the
         /// configuration.
+        ///
+        /// See also [`Reference::remote()`](crate::Reference::remote()).
         pub fn branch_remote<'a>(
             &self,
             short_branch_name: impl Into<&'a BStr>,