remote: add url=/token= to fetch/push/pull, plus dest_ref for fetch

Remote.fetch(), Remote.push(), and Remote.pull() could previously
only operate against the remote's configured name/URL, forcing
anyone who wanted to use an alternate URL (e.g. with an embedded
credential) to first rewrite the remote's permanent config via
set_url() -- persisting a token to .git/config as a side effect
just to do a single operation. All three shell out to the
underlying git transport command with the remote's name hardcoded
as the target; git remote update/rename/set-url/prune etc. are not
affected since those are config-only commands that don't accept an
arbitrary URL to begin with.

Add to Remote.fetch(), Remote.push(), and Remote.pull():

- url: use this URL for this call only. The remote's stored config
  is never read or written for the transport target when given; it
  takes precedence over the remote's name/configured url.

- token: optional credential embedded into url's authority
  component for this call only (http/https only). Never written to
  config or logged, and scrubbed from GitCommandError text if the
  call fails, so a failure can't leak the token via an
  exception/log message.

Additionally, Remote.fetch() gets dest_ref (fetch-only -- push
writes directly to the named destination ref regardless of url=,
and pull's merge target is the checked-out branch, so neither has
fetch's FETCH_HEAD-only footgun): a *bare* refspec entry (no
':dst') only updates FETCH_HEAD when fetching from an anonymous
url, because unlike a named/configured remote, git has no
remote.<name>.fetch pattern to complete a destination from.
dest_ref lets a caller ask for a normal tracking ref instead:
  * True             -> refs/remotes/<this-remote-name>/<branch>
  * '...{branch}...' -> templated destination, applied per-entry
                        when refspec is a list
  * plain string      -> used verbatim (single bare entry only)
Entries that already contain ':' are left untouched. Raises
ValueError if given without url=, or if a plain-string dest_ref is
combined with more than one bare refspec entry; raises TypeError
for any other dest_ref type.

Existing calls (no url=/token=/dest_ref=) are unaffected on all
three methods; behavior and the 'no refspec configured' assertion
are unchanged for that path on fetch/pull.

Adds test coverage for: one-off URL fetch/push/pull (each
confirming the configured remote url/config is untouched
afterwards and, for push/pull, that the operation actually took
effect against the alternate target), skipping the
refspec-assertion when url= is given, token= rejecting non-http(s)
urls on all three methods, token redaction in the raised
GitCommandError on failure for all three, dest_ref=True creating a
real tracking ref, a '{branch}' template applied across a list of
refspecs, a plain-string dest_ref, explicit 'src:dst' refspecs
being left untouched by dest_ref, and the ValueError/TypeError
validation paths.

Author: cumulus13

git/remote.py

@@ -10,6 +10,7 @@
 import contextlib
 import logging
 import re
+from urllib.parse import urlsplit, urlunsplit
 
 from git.cmd import Git, handle_process_output
 from git.compat import defenc, force_text
@@ -1008,6 +1009,9 @@ def fetch(
         kill_after_timeout: Union[None, float] = None,
         allow_unsafe_protocols: bool = False,
         allow_unsafe_options: bool = False,
+        url: Optional[str] = None,
+        token: Optional[str] = None,
+        dest_ref: Union[bool, str, None] = None,
         **kwargs: Any,
     ) -> IterableList[FetchInfo]:
         """Fetch the latest changes for this remote.
@@ -1028,6 +1032,16 @@ def fetch(
             does) - supplying a list rather than a string for 'refspec' will make use of
             this facility.
 
+            :note:
+                A *bare* source name with no ``:<dst>`` (e.g. ``"main"``) only updates
+                ``FETCH_HEAD`` when fetching from a remote by name, because git can
+                complete the destination from that remote's configured fetch refspec.
+                When fetching from an explicit ``url`` instead (no such config exists
+                for an anonymous URL), a bare name updates ``FETCH_HEAD`` only and
+                creates or updates no local ref at all. Use ``dest_ref`` below, or
+                spell out ``"<branch>:refs/remotes/<name>/<branch>"`` yourself, to get
+                a normal tracking ref out of a ``url=`` fetch.
+
         :param progress:
             See the :meth:`push` method.
 
@@ -1044,6 +1058,33 @@ def fetch(
         :param allow_unsafe_options:
             Allow unsafe options to be used, like ``--upload-pack``.
 
+        :param url:
+            Fetch from this URL instead of the remote's configured URL, for this
+            call only. The remote's stored config (``.git/config``) is never
+            written to or read for the transport target when this is given.
+            Takes precedence over the remote's name/configured url.
+
+        :param token:
+            Optional credential to embed in ``url`` for this call only (e.g. a
+            personal access token). Only used together with ``url``, and only
+            for ``http://``/``https://`` URLs. Never written to config, never
+            logged; kept out of :class:`FetchInfo`/exception text on failure.
+
+        :param dest_ref:
+            Only meaningful together with ``url``. Expands any *bare* (no ``:dst``)
+            entry in ``refspec`` into a full ``<branch>:<dst>`` mapping before
+            fetching, so the fetch updates a real local ref instead of only
+            ``FETCH_HEAD``. Entries that already contain a ``:`` are left untouched.
+
+            - ``True``: derive ``dst`` as ``refs/remotes/<this-remote's-name>/<branch>``
+              for each bare entry -- i.e. behave like a normal named-remote fetch would.
+            - A string containing ``{branch}``: used as a template for ``dst``, e.g.
+              ``"refs/remotes/upstream/{branch}"``.
+            - A plain string with no ``{branch}``: used verbatim as ``dst``. Only valid
+              when ``refspec`` is a single bare name, not a list.
+            - ``None`` (default): no expansion; bare names behave as plain git would
+              (``FETCH_HEAD`` only).
+
         :param kwargs:
             Additional arguments to be passed to :manpage:`git-fetch(1)`.
 
@@ -1055,16 +1096,41 @@ def fetch(
             As fetch does not provide progress information to non-ttys, we cannot make
             it available here unfortunately as in the :meth:`push` method.
         """
-        if refspec is None:
+        if url is None and refspec is None:
             # No argument refspec, then ensure the repo's config has a fetch refspec.
             self._assert_refspec()
 
+        if dest_ref is not None and url is None:
+            raise ValueError("dest_ref is only meaningful together with url=")
+
         kwargs = add_progress(kwargs, self.repo.git, progress)
         if isinstance(refspec, list):
             args: Sequence[Optional[str]] = refspec
         else:
             args = [refspec]
 
+        if dest_ref is not None:
+
+            def _expand(ref: Optional[str]) -> Optional[str]:
+                if not ref or ":" in ref:
+                    return ref
+                if dest_ref is True:
+                    dst = f"refs/remotes/{self.name}/{ref}"
+                elif isinstance(dest_ref, str) and "{branch}" in dest_ref:
+                    dst = dest_ref.format(branch=ref)
+                elif isinstance(dest_ref, str):
+                    if isinstance(refspec, list) and len(refspec) > 1:
+                        raise ValueError(
+                            "dest_ref as a plain string only supports a single bare refspec entry; "
+                            "use '{branch}' as a template, or pass True, for multiple entries"
+                        )
+                    dst = dest_ref
+                else:
+                    raise TypeError("dest_ref must be True, a string, or None")
+                return f"{ref}:{dst}"
+
+            args = [_expand(ref) for ref in args]
+
         if not allow_unsafe_protocols:
             for ref in args:
                 if ref:
@@ -1076,10 +1142,41 @@ def fetch(
                 unsafe_options=self.unsafe_git_fetch_options,
             )
 
-        proc = self.repo.git.fetch(
-            "--", self, *args, as_process=True, with_stdout=False, universal_newlines=True, v=verbose, **kwargs
-        )
-        res = self._get_fetch_info_from_stderr(proc, progress, kill_after_timeout=kill_after_timeout)
+        # Determine the fetch target: an explicit one-off `url` (optionally with an
+        # embedded `token`) takes precedence over the remote's configured name/url.
+        # Neither is ever written to .git/config -- it only affects this invocation.
+        fetch_target: Union[str, "Remote"] = self
+        if url is not None:
+            if not allow_unsafe_protocols:
+                Git.check_unsafe_protocols(url)
+            if token is not None:
+                parsed = urlsplit(url)
+                if parsed.scheme not in ("http", "https"):
+                    raise ValueError("token= is only supported with http:// or https:// urls")
+                netloc = f"{token}@{parsed.hostname}"
+                if parsed.port:
+                    netloc += f":{parsed.port}"
+                fetch_target = urlunsplit((parsed.scheme, netloc, parsed.path, parsed.query, parsed.fragment))
+            else:
+                fetch_target = url
+
+        try:
+            proc = self.repo.git.fetch(
+                "--",
+                fetch_target,
+                *args,
+                as_process=True,
+                with_stdout=False,
+                universal_newlines=True,
+                v=verbose,
+                **kwargs,
+            )
+            res = self._get_fetch_info_from_stderr(proc, progress, kill_after_timeout=kill_after_timeout)
+        except GitCommandError as err:
+            # Never let a token embedded in the URL leak into an exception message.
+            if token is not None and token in str(err):
+                err.args = tuple(a.replace(token, "***") if isinstance(a, str) else a for a in err.args)
+            raise
         if hasattr(self.repo.odb, "update_cache"):
             self.repo.odb.update_cache()
         return res
@@ -1091,6 +1188,8 @@ def pull(
         kill_after_timeout: Union[None, float] = None,
         allow_unsafe_protocols: bool = False,
         allow_unsafe_options: bool = False,
+        url: Optional[str] = None,
+        token: Optional[str] = None,
         **kwargs: Any,
     ) -> IterableList[FetchInfo]:
         """Pull changes from the given branch, being the same as a fetch followed by a
@@ -1111,13 +1210,28 @@ def pull(
         :param allow_unsafe_options:
             Allow unsafe options to be used, like ``--upload-pack``.
 
+        :param url:
+            Pull from this URL instead of the remote's configured URL, for this
+            call only. The remote's stored config (``.git/config``) is never
+            written to or read for the transport target when this is given.
+            Takes precedence over the remote's name/configured url. As with plain
+            ``git pull``, the fetched commit is merged into your currently checked
+            out branch regardless of the source, so use with the same care you
+            would use interactively.
+
+        :param token:
+            Optional credential to embed in ``url`` for this call only (e.g. a
+            personal access token). Only used together with ``url``, and only
+            for ``http://``/``https://`` URLs. Never written to config, never
+            logged; kept out of exception text on failure.
+
         :param kwargs:
             Additional arguments to be passed to :manpage:`git-pull(1)`.
 
         :return:
             Please see :meth:`fetch` method.
         """
-        if refspec is None:
+        if url is None and refspec is None:
             # No argument refspec, then ensure the repo's config has a fetch refspec.
             self._assert_refspec()
         kwargs = add_progress(kwargs, self.repo.git, progress)
@@ -1133,10 +1247,40 @@ def pull(
                 unsafe_options=self.unsafe_git_pull_options,
             )
 
-        proc = self.repo.git.pull(
-            "--", self, refspec, with_stdout=False, as_process=True, universal_newlines=True, v=True, **kwargs
-        )
-        res = self._get_fetch_info_from_stderr(proc, progress, kill_after_timeout=kill_after_timeout)
+        # Same one-off-target mechanism as fetch(): an explicit `url` (optionally
+        # with an embedded `token`) takes precedence over the remote's configured
+        # name/url, and neither is ever written to .git/config.
+        pull_target: Union[str, "Remote"] = self
+        if url is not None:
+            if not allow_unsafe_protocols:
+                Git.check_unsafe_protocols(url)
+            if token is not None:
+                parsed = urlsplit(url)
+                if parsed.scheme not in ("http", "https"):
+                    raise ValueError("token= is only supported with http:// or https:// urls")
+                netloc = f"{token}@{parsed.hostname}"
+                if parsed.port:
+                    netloc += f":{parsed.port}"
+                pull_target = urlunsplit((parsed.scheme, netloc, parsed.path, parsed.query, parsed.fragment))
+            else:
+                pull_target = url
+
+        try:
+            proc = self.repo.git.pull(
+                "--",
+                pull_target,
+                refspec,
+                with_stdout=False,
+                as_process=True,
+                universal_newlines=True,
+                v=True,
+                **kwargs,
+            )
+            res = self._get_fetch_info_from_stderr(proc, progress, kill_after_timeout=kill_after_timeout)
+        except GitCommandError as err:
+            if token is not None and token in str(err):
+                err.args = tuple(a.replace(token, "***") if isinstance(a, str) else a for a in err.args)
+            raise
         if hasattr(self.repo.odb, "update_cache"):
             self.repo.odb.update_cache()
         return res
@@ -1148,6 +1292,8 @@ def push(
         kill_after_timeout: Union[None, float] = None,
         allow_unsafe_protocols: bool = False,
         allow_unsafe_options: bool = False,
+        url: Optional[str] = None,
+        token: Optional[str] = None,
         **kwargs: Any,
     ) -> PushInfoList:
         """Push changes from source branch in refspec to target branch in refspec.
@@ -1180,6 +1326,18 @@ def push(
         :param allow_unsafe_options:
             Allow unsafe options to be used, like ``--receive-pack``.
 
+        :param url:
+            Push to this URL instead of the remote's configured URL, for this call
+            only. The remote's stored config (``.git/config``) is never written to
+            or read for the transport target when this is given. Takes precedence
+            over the remote's name/configured url.
+
+        :param token:
+            Optional credential to embed in ``url`` for this call only (e.g. a
+            personal access token). Only used together with ``url``, and only for
+            ``http://``/``https://`` URLs. Never written to config, never logged;
+            kept out of exception text on failure.
+
         :param kwargs:
             Additional arguments to be passed to :manpage:`git-push(1)`.
 
@@ -1209,16 +1367,39 @@ def push(
                 unsafe_options=self.unsafe_git_push_options,
             )
 
-        proc = self.repo.git.push(
-            "--",
-            self,
-            refspec,
-            porcelain=True,
-            as_process=True,
-            universal_newlines=True,
-            kill_after_timeout=kill_after_timeout,
-            **kwargs,
-        )
+        # Same one-off-target mechanism as fetch(): an explicit `url` (optionally
+        # with an embedded `token`) takes precedence over the remote's configured
+        # name/url, and neither is ever written to .git/config.
+        push_target: Union[str, "Remote"] = self
+        if url is not None:
+            if not allow_unsafe_protocols:
+                Git.check_unsafe_protocols(url)
+            if token is not None:
+                parsed = urlsplit(url)
+                if parsed.scheme not in ("http", "https"):
+                    raise ValueError("token= is only supported with http:// or https:// urls")
+                netloc = f"{token}@{parsed.hostname}"
+                if parsed.port:
+                    netloc += f":{parsed.port}"
+                push_target = urlunsplit((parsed.scheme, netloc, parsed.path, parsed.query, parsed.fragment))
+            else:
+                push_target = url
+
+        try:
+            proc = self.repo.git.push(
+                "--",
+                push_target,
+                refspec,
+                porcelain=True,
+                as_process=True,
+                universal_newlines=True,
+                kill_after_timeout=kill_after_timeout,
+                **kwargs,
+            )
+        except GitCommandError as err:
+            if token is not None and token in str(err):
+                err.args = tuple(a.replace(token, "***") if isinstance(a, str) else a for a in err.args)
+            raise
         return self._get_push_info(proc, progress, kill_after_timeout=kill_after_timeout)
 
     @property