feat: add Repository::upstream_branch_and_remote_name_for_tracking_branch()

It's a way to learn about the Remote and upstream branch which would
match the given local tracking branch.

Author: Byron

gix/src/repository/config/branch.rs

@@ -5,7 +5,9 @@ use gix_ref::{FullName, FullNameRef};
 use crate::bstr::BStr;
 use crate::config::cache::util::ApplyLeniencyDefault;
 use crate::config::tree::{Branch, Push};
-use crate::repository::{branch_remote_ref_name, branch_remote_tracking_ref_name};
+use crate::repository::{
+    branch_remote_ref_name, branch_remote_tracking_ref_name, upstream_branch_and_remote_name_for_tracking_branch,
+};
 use crate::{push, remote};
 
 /// Query configuration related to branches.
@@ -20,19 +22,18 @@ impl crate::Repository {
         self.subsection_str_names_of("branch")
     }
 
-    /// Returns the validated reference on the remote associated with the given `name`,
+    /// Returns the validated reference name of the upstream branch on the remote associated with the given `name`,
     /// which will be used when *merging*.
-    /// The returned value corresponds to the `branch.<short_branch_name>.merge` configuration key.
+    /// The returned value corresponds to the `branch.<short_branch_name>.merge` configuration key for [`remote::Direction::Fetch`].
+    /// For the [push direction](`remote::Direction::Push`) the Git configuration is used for a variety of different outcomes,
+    /// similar to what would happen when running `git push <name>`.
     ///
-    /// Returns `None` if there is no value at the given key, or if no remote or remote ref is configured.
-    /// May return an error if the reference name to be returned is invalid.
+    /// Returns `None` if there is nothing configured, or if no remote or remote ref is configured.
     ///
     /// ### Note
     ///
-    /// This name refers to what Git calls upstream branch (as opposed to upstream *tracking* branch).
+    /// The returned name refers to what Git calls upstream branch (as opposed to upstream *tracking* 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")]
@@ -125,6 +126,26 @@ impl crate::Repository {
             .map(|res| res.map_err(Into::into))
     }
 
+    /// Given a local `tracking_branch` name, find the remote that maps to it along with the name of the branch on
+    /// the side of the remote, also called upstream branch.
+    ///
+    /// Return `Ok(None)` if there is no remote with fetch-refspecs that would match `tracking_branch` on the right-hand side,
+    /// or `Err` if the matches were ambiguous.
+    ///
+    /// ### Limitations
+    ///
+    /// A single valid mapping is required as fine-grained matching isn't implemented yet. This means that
+    pub fn upstream_branch_and_remote_name_for_tracking_branch(
+        &self,
+        tracking_branch: &FullNameRef,
+    ) -> Result<
+        Option<(Cow<'_, FullNameRef>, remote::Name<'_>)>,
+        upstream_branch_and_remote_name_for_tracking_branch::Error,
+    > {
+        for remote_name in self.remote_names() {}
+        todo!()
+    }
+
     /// Returns the unvalidated name of the remote associated with the given `short_branch_name`,
     /// typically `main` instead of `refs/heads/main`.
     /// In some cases, the returned name will be an URL.

gix/src/repository/mod.rs

@@ -360,6 +360,17 @@ pub mod branch_remote_tracking_ref_name {
     }
 }
 
+///
+pub mod upstream_branch_and_remote_name_for_tracking_branch {
+    /// The error returned by [Repository::upstream_branch_and_remote_name_for_tracking_branch()](crate::Repository::upstream_branch_and_remote_name_for_tracking_branch()).
+    #[derive(Debug, thiserror::Error)]
+    #[allow(missing_docs)]
+    pub enum Error {
+        #[error("The name of the tracking reference was invalid")]
+        ValidateTrackingRef(#[from] gix_validate::reference::name::Error),
+    }
+}
+
 ///
 #[cfg(feature = "attributes")]
 pub mod pathspec_defaults_ignore_case {