GitPython 3.1.61__py3-none-any.whl → 3.2.0__py3-none-any.whl

git/__init__.py

@@ -86,7 +86,7 @@ __all__ = [
     "to_hex_sha",
 ]
 
-__version__ = '3.1.61'
+__version__ = '3.2.0'
 
 from typing import Any, List, Optional, Sequence, TYPE_CHECKING, Tuple, Union
 
@@ -295,6 +295,6 @@ def refresh(path: Optional[PathLike] = None) -> None:
 try:
     refresh()
 except Exception as _exc:
-    raise ImportError("Failed to initialize: {0}".format(_exc)) from _exc
+    raise ImportError(f"Failed to initialize: {_exc}") from _exc
 
 # } END initialize git executable path

git/cmd.py

@@ -100,7 +100,7 @@ _logger = logging.getLogger(__name__)
 
 
 def handle_process_output(
-    process: "Git.AutoInterrupt" | Popen,
+    process: Union["Git.AutoInterrupt", Popen],
     stdout_handler: Union[
         None,
         Callable[[AnyStr], None],
@@ -395,9 +395,7 @@ class _AutoInterrupt:
         :raise git.exc.GitCommandError:
             If the return status is not 0.
         """
-        if stderr is None:
-            stderr_b = b""
-        stderr_b = force_bytes(data=stderr, encoding="utf-8")
+        stderr_b = force_bytes(data=stderr, encoding="utf-8") or b""
         status: Union[int, None]
         if self.proc is not None:
             status = self.proc.wait()
@@ -647,7 +645,9 @@ class Git(metaclass=_GitMeta):
         "_version_info_token",
     )
 
-    re_unsafe_protocol = re.compile(r"(.+)::.+")
+    # Match Git's leading transport selector, including an empty helper name.
+    # Git also selects the command-executing ext helper for an ext:// URL.
+    re_unsafe_protocol = re.compile(r"([A-Za-z0-9][A-Za-z0-9+.-]*|)::|ext://")
 
     unsafe_git_ls_remote_options = [
         # This option allows arbitrary command execution in git-ls-remote.
@@ -947,7 +947,8 @@ class Git(metaclass=_GitMeta):
 
         Apart from the usual protocols (http, git, ssh), Git allows "remote helpers"
         that have the form ``<transport>::<address>``. One of these helpers (``ext::``)
-        can be used to invoke any arbitrary command.
+        can be used to invoke any arbitrary command. Git also selects that helper
+        for ``ext://`` URLs and interprets the URL as a command path.
 
         See:
 
@@ -956,11 +957,19 @@ class Git(metaclass=_GitMeta):
         """
         match = cls.re_unsafe_protocol.match(url)
         if match:
-            protocol = match.group(1)
+            protocol = match.group(0)
             raise UnsafeProtocolError(
-                f"The `{protocol}::` protocol looks suspicious, use `allow_unsafe_protocols=True` to allow it."
+                f"The `{protocol}` protocol looks suspicious, use `allow_unsafe_protocols=True` to allow it."
             )
 
+    def _check_unsafe_protocols_in_args(self, args: Sequence[Any], kwargs: Mapping[str, Any]) -> None:
+        """Check positional operands and standalone values in rendered command options.
+
+        A short flag's split value can become the repository operand before ``--``.
+        """
+        for arg in self._unpack_args(args) + self.transform_kwargs(**kwargs):
+            self.check_unsafe_protocols(arg)
+
     @classmethod
     def _canonicalize_option_name(cls, option: str) -> str:
         """Return the option name used for unsafe-option checks.
@@ -1131,16 +1140,23 @@ class Git(metaclass=_GitMeta):
         self,
         *args: Any,
         allow_unsafe_options: bool = False,
+        allow_unsafe_protocols: bool = False,
         **kwargs: Any,
     ) -> Union[str, bytes, Tuple[int, Union[str, bytes], str], "Git.AutoInterrupt"]:
         """List references in a remote repository.
 
         :param allow_unsafe_options:
             Allow unsafe options, like ``--upload-pack`` or ``--exec``.
+
+        :param allow_unsafe_protocols:
+            Allow unsafe protocols to be used, like ``ext``. Positional arguments
+            and split short-option values are checked.
         """
         if not allow_unsafe_options:
             candidate_options = self._option_candidates(args, kwargs)
             Git.check_unsafe_options(options=candidate_options, unsafe_options=self.unsafe_git_ls_remote_options)
+        if not allow_unsafe_protocols:
+            self._check_unsafe_protocols_in_args(args, kwargs)
         return self._call_process("ls_remote", *args, **kwargs)
 
     @property
@@ -1180,52 +1196,112 @@ class Git(metaclass=_GitMeta):
     def execute(
         self,
         command: Union[str, Sequence[Any]],
+        istream: Union[None, int, BinaryIO] = None,
         *,
         as_process: Literal[True],
+        **subprocess_kwargs: Any,
     ) -> "AutoInterrupt": ...
 
     @overload
     def execute(
         self,
         command: Union[str, Sequence[Any]],
+        istream: Union[None, int, BinaryIO] = None,
         *,
         as_process: Literal[False] = False,
-        stdout_as_string: Literal[True],
-    ) -> Union[str, Tuple[int, str, str]]: ...
+        with_extended_output: Literal[False] = False,
+        stdout_as_string: Literal[True] = True,
+        with_stdout: Literal[True] = True,
+        **subprocess_kwargs: Any,
+    ) -> str: ...
 
     @overload
     def execute(
         self,
         command: Union[str, Sequence[Any]],
+        istream: Union[None, int, BinaryIO] = None,
         *,
         as_process: Literal[False] = False,
-        stdout_as_string: Literal[False] = False,
-    ) -> Union[bytes, Tuple[int, bytes, str]]: ...
+        with_extended_output: Literal[False] = False,
+        stdout_as_string: Literal[False],
+        universal_newlines: Literal[False] = False,
+        with_stdout: Literal[True] = True,
+        **subprocess_kwargs: Any,
+    ) -> bytes: ...
 
     @overload
     def execute(
         self,
         command: Union[str, Sequence[Any]],
+        istream: Union[None, int, BinaryIO] = None,
         *,
-        with_extended_output: Literal[False],
-        as_process: Literal[False],
-        stdout_as_string: Literal[True],
-    ) -> str: ...
+        as_process: Literal[False] = False,
+        with_extended_output: Literal[True],
+        stdout_as_string: Literal[True] = True,
+        with_stdout: Literal[True] = True,
+        **subprocess_kwargs: Any,
+    ) -> Tuple[int, str, str]: ...
 
     @overload
     def execute(
         self,
         command: Union[str, Sequence[Any]],
+        istream: Union[None, int, BinaryIO] = None,
         *,
-        with_extended_output: Literal[False],
-        as_process: Literal[False],
+        as_process: Literal[False] = False,
+        with_extended_output: Literal[True],
         stdout_as_string: Literal[False],
-    ) -> bytes: ...
+        universal_newlines: Literal[False] = False,
+        with_stdout: Literal[True] = True,
+        **subprocess_kwargs: Any,
+    ) -> Tuple[int, bytes, str]: ...
 
+    @overload
     def execute(
         self,
         command: Union[str, Sequence[Any]],
-        istream: Union[None, BinaryIO] = None,
+        istream: Union[None, int, BinaryIO] = None,
+        *,
+        as_process: Literal[False] = False,
+        with_extended_output: Literal[True],
+        **subprocess_kwargs: Any,
+    ) -> Tuple[int, Union[str, bytes, None], str]: ...
+
+    @overload
+    def execute(
+        self,
+        command: Union[str, Sequence[Any]],
+        istream: Union[None, int, BinaryIO] = None,
+        *,
+        as_process: Literal[False] = False,
+        with_extended_output: Literal[False] = False,
+        **subprocess_kwargs: Any,
+    ) -> Union[str, bytes, None]: ...
+
+    @overload
+    def execute(
+        self,
+        command: Union[str, Sequence[Any]],
+        istream: Union[None, int, BinaryIO] = None,
+        with_extended_output: bool = False,
+        with_exceptions: bool = True,
+        as_process: bool = False,
+        output_stream: Union[None, BinaryIO] = None,
+        stdout_as_string: bool = True,
+        kill_after_timeout: Union[None, float] = None,
+        with_stdout: bool = True,
+        universal_newlines: bool = False,
+        shell: Union[None, bool] = None,
+        env: Union[None, Mapping[str, str]] = None,
+        max_chunk_size: int = io.DEFAULT_BUFFER_SIZE,
+        strip_newline_in_stdout: bool = True,
+        **subprocess_kwargs: Any,
+    ) -> Union[None, str, bytes, Tuple[int, Union[str, bytes, None], str], AutoInterrupt]: ...
+
+    def execute(
+        self,
+        command: Union[str, Sequence[Any]],
+        istream: Union[None, int, BinaryIO] = None,
         with_extended_output: bool = False,
         with_exceptions: bool = True,
         as_process: bool = False,
@@ -1239,7 +1315,7 @@ class Git(metaclass=_GitMeta):
         max_chunk_size: int = io.DEFAULT_BUFFER_SIZE,
         strip_newline_in_stdout: bool = True,
         **subprocess_kwargs: Any,
-    ) -> Union[str, bytes, Tuple[int, Union[str, bytes], str], AutoInterrupt]:
+    ) -> Union[None, str, bytes, Tuple[int, Union[str, bytes, None], str], AutoInterrupt]:
         R"""Handle executing the command, and consume and return the returned
         information (stdout).
 
@@ -1303,9 +1379,9 @@ class Git(metaclass=_GitMeta):
             carefully considered, due to the following limitations:
 
             1. This feature is not supported at all on Windows.
-            2. Effectiveness may vary by operating system. ``ps --ppid`` is used to
-               enumerate child processes, which is available on most GNU/Linux systems
-               but not most others.
+            2. Enumerating child processes requires ``pgrep -P``, or a ``ps`` command
+               supporting the POSIX ``-A`` and ``-o`` options if ``pgrep`` is not
+               installed. Effectiveness may vary on systems without these commands.
             3. Deeper descendants do not receive signals, though they may sometimes
                terminate as a consequence of their parent processes being killed.
             4. `kill_after_timeout` uses ``SIGKILL``, which can have negative side
@@ -1465,14 +1541,24 @@ class Git(metaclass=_GitMeta):
 
                 This callback implementation would be ineffective and unsafe on Windows.
                 """
-                p = Popen(["ps", "--ppid", str(pid)], stdout=PIPE)
                 child_pids = []
-                if p.stdout is not None:
-                    for line in p.stdout:
-                        if len(line.split()) > 0:
-                            local_pid = (line.split())[0]
-                            if local_pid.isdigit():
-                                child_pids.append(int(local_pid))
+                try:
+                    p = Popen(["pgrep", "-P", str(pid)], stdout=PIPE)
+                except FileNotFoundError:
+                    # POSIX ps does not support selecting by parent PID.
+                    with Popen(["ps", "-A", "-o", "pid=", "-o", "ppid="], stdout=PIPE) as p:
+                        if p.stdout is not None:
+                            for line in p.stdout:
+                                fields = line.split()
+                                if len(fields) == 2 and all(field.isdigit() for field in fields):
+                                    if int(fields[1]) == pid:
+                                        child_pids.append(int(fields[0]))
+                else:
+                    with p:
+                        if p.stdout is not None:
+                            for line in p.stdout:
+                                if line.strip().isdigit():
+                                    child_pids.append(int(line))
                 try:
                     os.kill(pid, signal.SIGKILL)
                     for child_pid in child_pids:
@@ -1493,7 +1579,7 @@ class Git(metaclass=_GitMeta):
                 err = f'Timeout: the command "{" ".join(redacted_command)}" did not complete in {timeout:g} secs.'
                 return err if universal_newlines else err.encode(defenc)
 
-            def communicate() -> Tuple[AnyStr, AnyStr]:
+            def communicate() -> Tuple[Union[str, bytes, None], Union[str, bytes, None]]:
                 assert watchdog is not None
                 assert kill_check is not None
                 watchdog.start()
@@ -1513,8 +1599,8 @@ class Git(metaclass=_GitMeta):
 
         # Wait for the process to return.
         status = 0
-        stdout_value: Union[str, bytes] = b""
-        stderr_value: Union[str, bytes] = b""
+        stdout_value: Union[str, bytes, None] = b""
+        stderr_value: Union[str, bytes, None] = b""
         newline = "\n" if universal_newlines else b"\n"
         try:
             if output_stream is None:
@@ -1556,7 +1642,7 @@ class Git(metaclass=_GitMeta):
         if self.GIT_PYTHON_TRACE == "full":
             cmdstr = " ".join(redacted_command)
 
-            def as_text(stdout_value: Union[bytes, str]) -> str:
+            def as_text(stdout_value: Union[bytes, str, None]) -> str:
                 return not output_stream and safe_decode(stdout_value) or "<OUTPUT_STREAM>"
 
             # END as_text
@@ -1581,6 +1667,8 @@ class Git(metaclass=_GitMeta):
         if isinstance(stdout_value, bytes) and stdout_as_string:  # Could also be output_stream.
             stdout_value = safe_decode(stdout_value)
 
+        # stderr is always captured through PIPE.
+        assert stderr_value is not None
         # Allow access to the command's status code.
         if with_extended_output:
             return (status, stdout_value, safe_decode(stderr_value))
@@ -1725,6 +1813,12 @@ class Git(metaclass=_GitMeta):
             This allows your commands to call git more conveniently, as ``None`` is
             realized as non-existent.
 
+            Positional arguments may intentionally contain command options. Higher-level
+            APIs must separate their operands with ``--`` where the Git command supports
+            it, or reject option-shaped operands where Git reparses them internally (for
+            example, ``pull`` and ``remote update``). Shell quoting cannot prevent Git
+            from interpreting a leading-dash argument as an option.
+
         :param kwargs:
             Contains key-values for the following:
 
@@ -1819,7 +1913,7 @@ class Git(metaclass=_GitMeta):
             raise ValueError("Failed to parse header: %r" % header_line)
         return (tokens[0], tokens[1], int(tokens[2]))
 
-    def _prepare_ref(self, ref: AnyStr) -> bytes:
+    def _prepare_ref(self, ref: object) -> bytes:
         # Required for command to separate refs on stdin, as bytes.
         if isinstance(ref, bytes):
             # Assume 40 bytes hexsha - bin-to-ascii for some reason returns bytes, not text.
@@ -1846,7 +1940,7 @@ class Git(metaclass=_GitMeta):
         cmd = cast("Git.AutoInterrupt", cmd)
         return cmd
 
-    def __get_object_header(self, cmd: "Git.AutoInterrupt", ref: AnyStr) -> Tuple[str, str, int]:
+    def __get_object_header(self, cmd: "Git.AutoInterrupt", ref: Union[str, bytes]) -> Tuple[str, str, int]:
         if cmd.stdin and cmd.stdout:
             cmd.stdin.write(self._prepare_ref(ref))
             cmd.stdin.flush()
@@ -1854,7 +1948,7 @@ class Git(metaclass=_GitMeta):
         else:
             raise ValueError("cmd stdin was empty")
 
-    def get_object_header(self, ref: str) -> Tuple[str, str, int]:
+    def get_object_header(self, ref: Union[str, bytes]) -> Tuple[str, str, int]:
         """Use this method to quickly examine the type and size of the object behind the
         given ref.
 
@@ -1868,7 +1962,7 @@ class Git(metaclass=_GitMeta):
         cmd = self._get_persistent_cmd("cat_file_header", "cat_file", batch_check=True)
         return self.__get_object_header(cmd, ref)
 
-    def get_object_data(self, ref: str) -> Tuple[str, str, int, bytes]:
+    def get_object_data(self, ref: Union[str, bytes]) -> Tuple[str, str, int, bytes]:
         """Similar to :meth:`get_object_header`, but returns object data as well.
 
         :return:
@@ -1882,7 +1976,7 @@ class Git(metaclass=_GitMeta):
         del stream
         return (hexsha, typename, size, data)
 
-    def stream_object_data(self, ref: str) -> Tuple[str, str, int, "Git.CatFileContentStream"]:
+    def stream_object_data(self, ref: Union[str, bytes]) -> Tuple[str, str, int, "Git.CatFileContentStream"]:
         """Similar to :meth:`get_object_data`, but returns the data as a stream.
 
         :return: