GitPython 3.1.48__tar.gz → 3.1.52__tar.gz

{gitpython-3.1.48 → gitpython-3.1.52}/AUTHORS

@@ -57,5 +57,6 @@ Contributors are:
 -Jonas Scharpf <jonas.scharpf _at_ checkmk.com>
 -Gordon Marx
 -Enji Cooper
+-Harshita Yadav <harshitayadav504 _at_ gmail.com>
 
 Portions derived from other open source works and are clearly marked.

gitpython-3.1.52/CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# How to contribute
+
+The following is a short step-by-step rundown of what one typically would do to contribute.
+
+- [Fork this project](https://github.com/gitpython-developers/GitPython/fork) on GitHub.
+- For setting up the environment to run the self tests, please run `init-tests-after-clone.sh`.
+- Please try to **write a test that fails unless the contribution is present.**
+- Try to avoid massive commits and prefer to take small steps, with one commit for each.
+- Feel free to add yourself to AUTHORS file.
+- Create a pull request.
+
+## Quality expectations
+
+Contributions must be made with care and meet the quality bar of the surrounding code.
+That means a change should not leave GitPython worse than it was before: it should be
+readable, maintainable, tested where practical, documented and consistent with the
+existing style and behavior.
+
+A contribution that works only narrowly but lowers the quality of the
+codebase may be declined. The maintainers may not always be able to provide
+detailed feedback.
+
+## AI-assisted contributions
+
+If AI edits files for you, disclose it in the pull request description and commit
+metadata. Prefer making the agent identity part of the commit, for example by using
+an AI author such as `$agent $version <ai-agent@example.invalid>` or a co-author via
+a `Co-authored-by: <agent-identity>` trailer.
+
+Agents operating through a person's GitHub account must identify themselves. For
+example, comments posted by an agent should say so directly with phrases like
+`AI agent on behalf of <person>: ...`.
+
+Fully AI-generated comments on pull requests or issues must also be disclosed.
+Undisclosed AI-generated comments may lead to the pull request or issue being closed.
+
+AI-assisted proofreading or wording polish does not need disclosure, but it is still
+courteous to mention it when the AI materially influenced the final text.
+
+Automated or "full-auto" AI contributions without a human responsible for reviewing
+and standing behind the work may be closed.
+
+## Fuzzing Test Specific Documentation
+
+For details related to contributing to the fuzzing test suite and OSS-Fuzz integration, please 
+refer to the dedicated [fuzzing README](./fuzzing/README.md).

{gitpython-3.1.48 → gitpython-3.1.52/GitPython.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GitPython
-Version: 3.1.48
+Version: 3.1.52
 Summary: GitPython is a Python library used to interact with Git repositories
 Home-page: https://github.com/gitpython-developers/GitPython
 Author: Sebastian Thiel, Michael Trier

{gitpython-3.1.48/GitPython.egg-info → gitpython-3.1.52}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GitPython
-Version: 3.1.48
+Version: 3.1.52
 Summary: GitPython is a Python library used to interact with Git repositories
 Home-page: https://github.com/gitpython-developers/GitPython
 Author: Sebastian Thiel, Michael Trier

gitpython-3.1.52/VERSION

@@ -0,0 +1 @@
+3.1.52

{gitpython-3.1.48 → gitpython-3.1.52}/doc/source/changes.rst

@@ -2,6 +2,51 @@
 Changelog
 =========
 
+3.1.52
+======
+
+A security fix for
+https://github.com/gitpython-developers/GitPython/security/advisories/GHSA-rwj8-pgh3-r573.
+
+See the following for all changes.
+https://github.com/gitpython-developers/GitPython/releases/tag/3.1.52
+
+3.1.51
+======
+
+This is primarily a security release. It prevents additional argument-injection
+paths that could allow execution of arbitrary commands or writing to arbitrary
+files through unsafe Git options (GHSA-956x-8gvw-wg5v), and closes bypasses of
+the existing protections using abbreviated long options or joined short options
+(GHSA-2f96-g7mh-g2hx).
+
+The release also improves support for relative worktree paths and diffs against
+the empty tree, preserves stderr from failed diff processes, supports relative
+configuration include paths, and includes assorted documentation, typing, test,
+and CI improvements.
+
+See the following for all changes.
+https://github.com/gitpython-developers/GitPython/releases/tag/3.1.51
+
+3.1.50
+======
+
+Save setting of configuration values, this time sections as well, as follow-up to 3.1.49.
+
+See the following for all changes.
+https://github.com/gitpython-developers/GitPython/releases/tag/3.1.50
+
+3.1.49
+======
+
+Save setting of configuration values, 
+which could be used to inject other more configuration.
+
+Also more conforming `rev-parse` implementation.
+
+See the following for all changes.
+https://github.com/gitpython-developers/GitPython/releases/tag/3.1.49
+
 3.1.48
 ======
 

{gitpython-3.1.48 → gitpython-3.1.52}/git/__init__.py

@@ -86,7 +86,7 @@ __all__ = [
     "to_hex_sha",
 ]
 
-__version__ = '3.1.48'
+__version__ = '3.1.52'
 
 from typing import Any, List, Optional, Sequence, TYPE_CHECKING, Tuple, Union
 

{gitpython-3.1.48 → gitpython-3.1.52}/git/cmd.py

@@ -649,6 +649,11 @@ class Git(metaclass=_GitMeta):
 
     re_unsafe_protocol = re.compile(r"(.+)::.+")
 
+    unsafe_git_ls_remote_options = [
+        # This option allows arbitrary command execution in git-ls-remote.
+        "--upload-pack",
+    ]
+
     def __getstate__(self) -> Dict[str, Any]:
         return slots_to_dict(self, exclude=self._excluded_)
 
@@ -898,29 +903,34 @@ class Git(metaclass=_GitMeta):
 
     @overload
     @classmethod
-    def polish_url(cls, url: str, is_cygwin: Literal[False] = ...) -> str: ...
+    def polish_url(cls, url: str, is_cygwin: Literal[False] = ..., expand_vars: bool = ...) -> str: ...
 
     @overload
     @classmethod
-    def polish_url(cls, url: str, is_cygwin: Union[None, bool] = None) -> str: ...
+    def polish_url(cls, url: str, is_cygwin: Union[None, bool] = None, expand_vars: bool = True) -> str: ...
 
     @classmethod
-    def polish_url(cls, url: str, is_cygwin: Union[None, bool] = None) -> PathLike:
+    def polish_url(cls, url: str, is_cygwin: Union[None, bool] = None, expand_vars: bool = True) -> PathLike:
         """Remove any backslashes from URLs to be written in config files.
 
         Windows might create config files containing paths with backslashes, but git
         stops liking them as it will escape the backslashes. Hence we undo the escaping
         just to be sure.
+
+        :param expand_vars:
+            Expand environment variables and an initial ``~``. Disable this for values
+            obtained from an untrusted source, such as remote URLs.
         """
         if is_cygwin is None:
             is_cygwin = cls.is_cygwin()
 
         if is_cygwin:
-            url = cygpath(url)
+            url = cygpath(url, expand_vars=expand_vars)
         else:
-            url = os.path.expandvars(url)
-            if url.startswith("~"):
-                url = os.path.expanduser(url)
+            if expand_vars:
+                url = os.path.expandvars(url)
+                if url.startswith("~"):
+                    url = os.path.expanduser(url)
             url = url.replace("\\\\", "\\").replace("\\", "/")
         return url
 
@@ -961,17 +971,80 @@ class Git(metaclass=_GitMeta):
 
     @classmethod
     def check_unsafe_options(cls, options: List[str], unsafe_options: List[str]) -> None:
-        """Check for unsafe options.
-
-        Some options that are passed to ``git <command>`` can be used to execute
-        arbitrary commands. These are blocked by default.
+        """Raise :class:`~git.exc.UnsafeOptionError` for blocked option spellings.
+
+        In addition to exact matches, this rejects abbreviated long options accepted
+        by Git (for example, ``--upl`` for ``--upload-pack``) and unsafe short options
+        whose values are joined to the same token, including after clusterable flags
+        (for example, ``-uVALUE`` and ``-fuVALUE``).
+
+        A list containing only bare names is treated as normalized keyword arguments,
+        so multi-character names such as ``upload_p`` are checked as long-option
+        abbreviations. If any item starts with ``-``, the list is treated as tokenized
+        command-line input: bare items can be option values and are not checked as
+        abbreviations. Thus ``["--origin", "upload"]`` is allowed. Single-dash options
+        use short-option parsing rather than broad prefix matching, preserving safe
+        attached values such as ``-oupstream`` and ``-bcurrent``.
+
+        Some options passed to ``git <command>`` can execute arbitrary commands and
+        are therefore blocked by default unless the caller explicitly allows them.
         """
         # Options can be of the form `foo`, `--foo`, `--foo bar`, or `--foo=bar`.
+        # Git accepts any unambiguous prefix of a long option, so an abbreviated
+        # spelling such as `--upl` for `--upload-pack` must be rejected too. An
+        # option is unsafe if its canonical name is a prefix of any blocked
+        # option's canonical name. Only long options and multi-character kwargs
+        # can be abbreviations; single-character short options remain exact-match
+        # only.
         canonical_unsafe_options = {cls._canonicalize_option_name(option): option for option in unsafe_options}
+        unsafe_short_options = {
+            canonical: option
+            for canonical, option in canonical_unsafe_options.items()
+            if option.startswith("-") and not option.startswith("--") and len(canonical) == 1
+        }
+        # These value-less Git flags can be clustered before another short option
+        # (for example, ``-fuVALUE``). Stop at any other character because it may
+        # begin an attached value, as ``o`` does in the safe option ``-oupstream``.
+        clusterable_short_options = frozenset("46flnqsv")
+        options_are_kwargs = all(not option.startswith("-") for option in options)
         for option in options:
-            unsafe_option = canonical_unsafe_options.get(cls._canonicalize_option_name(option))
+            candidate = cls._canonicalize_option_name(option)
+            if not candidate:
+                continue
+            unsafe_option = canonical_unsafe_options.get(candidate)
             if unsafe_option is not None:
                 raise UnsafeOptionError(f"{unsafe_option} is not allowed, use `allow_unsafe_options=True` to allow it.")
+            option_token = option.split("=", 1)[0].split(None, 1)[0]
+            if option_token.startswith("-") and not option_token.startswith("--"):
+                for option_char in option_token[1:]:
+                    unsafe_option = unsafe_short_options.get(option_char)
+                    if unsafe_option is not None:
+                        raise UnsafeOptionError(
+                            f"{unsafe_option} is not allowed, use `allow_unsafe_options=True` to allow it."
+                        )
+                    if option_char not in clusterable_short_options:
+                        break
+            if not (option.startswith("--") or (options_are_kwargs and len(candidate) > 1)):
+                continue
+            for canonical, unsafe_option in canonical_unsafe_options.items():
+                if canonical.startswith(candidate):
+                    raise UnsafeOptionError(
+                        f"{unsafe_option} is not allowed, use `allow_unsafe_options=True` to allow it."
+                    )
+
+    @classmethod
+    def _option_candidates(cls, args: Sequence[Any] = (), kwargs: Optional[Mapping[str, Any]] = None) -> List[str]:
+        """Collect possible option spellings before command-line transformation."""
+        options = [
+            option for option in cls._unpack_args([arg for arg in args if arg is not None]) if option.startswith("-")
+        ]
+        if kwargs:
+            for key, value in kwargs.items():
+                values = value if isinstance(value, (list, tuple)) else (value,)
+                if any(value is True or (value is not False and value is not None) for value in values):
+                    key = str(key)
+                    options.append(f"-{key}" if len(key) == 1 else f"--{dashify(key)}")
+        return options
 
     AutoInterrupt: TypeAlias = _AutoInterrupt
 
@@ -1030,6 +1103,22 @@ class Git(metaclass=_GitMeta):
 
         self._persistent_git_options = self.transform_kwargs(split_single_char_options=True, **kwargs)
 
+    def ls_remote(
+        self,
+        *args: Any,
+        allow_unsafe_options: 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``.
+        """
+        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)
+        return self._call_process("ls_remote", *args, **kwargs)
+
     @property
     def working_dir(self) -> Union[None, PathLike]:
         """:return: Git directory we are working on"""
@@ -1131,9 +1220,28 @@ class Git(metaclass=_GitMeta):
         information (stdout).
 
         :param command:
-            The command argument list to execute.
-            It should be a sequence of program arguments, or a string. The
-            program to execute is the first item in the args sequence or string.
+            The command to execute. A sequence of program arguments is recommended.
+            A string is also accepted, but its meaning is strongly platform-dependent.
+
+            By default, a shell is not used. On Unix-like systems, a string is the whole
+            program name (so ``"git log -n 1"`` raises :class:`GitCommandNotFound`). On
+            Windows, the program parses the arguments itself, so multi-word strings can
+            work but are not portable.
+
+            Avoid ``shell=True`` (and :attr:`Git.USE_SHELL`): this runs the command in
+            a shell, which is generally unsafe. The shell interprets metacharacters
+            such as ``;``, ``|``, ``&``, ``$(...)``, ``$VAR``, ``%VAR%``, and ``^``
+            (depending on the platform) as syntax. Any untrusted text in the command
+            can then execute arbitrary OS commands. See :attr:`Git.USE_SHELL`.
+
+            Producing a sequence automatically by :func:`shlex.split` and passing it
+            as the command is far safer than ``shell=True``. But :func:`shlex.split`
+            parses POSIX shell syntax on all systems, and the result is still unsafe
+            for anything but *fixed, fully trusted* strings. Do not use it on strings
+            built by interpolating values: whitespace or quoting in an untrusted value
+            can still inject arguments. For input derived in any way from untrusted
+            data, build the argument sequence yourself, while ensuring each argument
+            is fully sanitized.
 
         :param istream:
             Standard input filehandle passed to :class:`subprocess.Popen`.
@@ -1201,6 +1309,11 @@ class Git(metaclass=_GitMeta):
             needed (nor useful) to work around any known operating system specific
             issues.
 
+            On Unix-like systems, when migrating away from passing string commands with
+            ``shell=True``, :func:`shlex.split` may serve as a transitional step in rare
+            cases, with extreme care. (Drop ``shell=True`` and pass the resulting
+            sequence as the command.) See the `command` parameter above on the risks.
+
         :param env:
             A dictionary of environment variables to be passed to
             :class:`subprocess.Popen`.
@@ -1512,7 +1625,7 @@ class Git(metaclass=_GitMeta):
         return args
 
     @classmethod
-    def _unpack_args(cls, arg_list: Sequence[str]) -> List[str]:
+    def _unpack_args(cls, arg_list: Sequence[Any]) -> List[str]:
         outlist = []
         if isinstance(arg_list, (list, tuple)):
             for arg in arg_list:
@@ -1588,7 +1701,7 @@ class Git(metaclass=_GitMeta):
 
         turns into::
 
-            git rev-list --max-count=10 --header=master
+            git rev-list --max-count=10 --header master
 
         :return:
             Same as :meth:`execute`. If no args are given, used :meth:`execute`'s

{gitpython-3.1.48 → gitpython-3.1.52}/git/config.py

@@ -72,6 +72,9 @@ CONDITIONAL_INCLUDE_REGEXP = re.compile(r"(?<=includeIf )\"(gitdir|gitdir/i|onbr
 See: https://git-scm.com/docs/git-config#_conditional_includes
 """
 
+UNSAFE_CONFIG_CHARS_RE = re.compile(r"[\r\n\x00]")
+"""Characters that cannot be safely written in config names or values."""
+
 
 class MetaParserBuilder(abc.ABCMeta):  # noqa: B024
     """Utility class wrapping base-class methods into decorators that assure read-only
@@ -631,6 +634,8 @@ class GitConfigParser(cp.RawConfigParser, metaclass=MetaParserBuilder):
             files_to_read = list(self._file_or_files)
         # END ensure we have a copy of the paths to handle
 
+        files_to_read = [osp.abspath(path) if isinstance(path, (str, os.PathLike)) else path for path in files_to_read]
+
         seen = set(files_to_read)
         num_read_include_files = 0
         while files_to_read:
@@ -778,6 +783,7 @@ class GitConfigParser(cp.RawConfigParser, metaclass=MetaParserBuilder):
 
     def add_section(self, section: "cp._SectionName") -> None:
         """Assures added options will stay in order."""
+        self._assure_config_name_safe(section, "section")
         return super().add_section(section)
 
     @property
@@ -882,6 +888,30 @@ class GitConfigParser(cp.RawConfigParser, metaclass=MetaParserBuilder):
             return str(value)
         return force_text(value)
 
+    def _value_to_string_safe(self, value: Union[str, bytes, int, float, bool]) -> str:
+        value_str = self._value_to_string(value)
+        if UNSAFE_CONFIG_CHARS_RE.search(value_str):
+            raise ValueError("Git config values must not contain CR, LF, or NUL")
+        return value_str
+
+    def _assure_config_name_safe(self, name: "cp._SectionName", label: str) -> None:
+        if isinstance(name, str) and UNSAFE_CONFIG_CHARS_RE.search(name):
+            raise ValueError("Git config %s names must not contain CR, LF, or NUL" % label)
+
+    @needs_values
+    @set_dirty_and_flush_changes
+    def set(
+        self,
+        section: str,
+        option: str,
+        value: Union[str, bytes, int, float, bool, None] = None,
+    ) -> None:
+        self._assure_config_name_safe(section, "section")
+        self._assure_config_name_safe(option, "option")
+        if value is not None:
+            value = self._value_to_string_safe(value)
+        return super().set(section, option, value)
+
     @needs_values
     @set_dirty_and_flush_changes
     def set_value(self, section: str, option: str, value: Union[str, bytes, int, float, bool]) -> "GitConfigParser":
@@ -902,9 +932,12 @@ class GitConfigParser(cp.RawConfigParser, metaclass=MetaParserBuilder):
         :return:
             This instance
         """
+        self._assure_config_name_safe(section, "section")
+        self._assure_config_name_safe(option, "option")
+        value_str = self._value_to_string_safe(value)
         if not self.has_section(section):
             self.add_section(section)
-        self.set(section, option, self._value_to_string(value))
+        super().set(section, option, value_str)
         return self
 
     @needs_values
@@ -929,9 +962,12 @@ class GitConfigParser(cp.RawConfigParser, metaclass=MetaParserBuilder):
         :return:
             This instance
         """
+        self._assure_config_name_safe(section, "section")
+        self._assure_config_name_safe(option, "option")
+        value_str = self._value_to_string_safe(value)
         if not self.has_section(section):
             self.add_section(section)
-        self._sections[section].add(option, self._value_to_string(value))
+        self._sections[section].add(option, value_str)
         return self
 
     def rename_section(self, section: str, new_name: str) -> "GitConfigParser":
@@ -948,6 +984,7 @@ class GitConfigParser(cp.RawConfigParser, metaclass=MetaParserBuilder):
         """
         if not self.has_section(section):
             raise ValueError("Source section '%s' doesn't exist" % section)
+        self._assure_config_name_safe(new_name, "section")
         if self.has_section(new_name):
             raise ValueError("Destination section '%s' already exists" % new_name)
 

{gitpython-3.1.48 → gitpython-3.1.52}/git/diff.py

@@ -3,7 +3,7 @@
 # This module is part of GitPython and is released under the
 # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
 
-__all__ = ["DiffConstants", "NULL_TREE", "INDEX", "Diffable", "DiffIndex", "Diff"]
+__all__ = ["DiffConstants", "NULL_TREE", "NULL_TREE_SHA", "INDEX", "Diffable", "DiffIndex", "Diff"]
 
 import enum
 import re
@@ -84,6 +84,9 @@ This is an alias of :const:`DiffConstants.NULL_TREE`, which may also be accessed
 :const:`git.NULL_TREE` and :const:`Diffable.NULL_TREE`.
 """
 
+NULL_TREE_SHA = "4b825dc642cb6eb9a060e54bf8d69288fbee4904"
+"""SHA of Git's canonical empty tree object."""
+
 INDEX: Literal[DiffConstants.INDEX] = DiffConstants.INDEX
 """Stand-in indicating you want to diff against the index.
 
@@ -599,7 +602,14 @@ class Diff:
 
         # FIXME: Here SLURPING raw, need to re-phrase header-regexes linewise.
         text_list: List[bytes] = []
-        handle_process_output(proc, text_list.append, None, finalize_process, decode_streams=False)
+        stderr_list: List[bytes] = []
+
+        def finalize_process_with_stderr(proc: Union["Popen", "Git.AutoInterrupt"]) -> None:
+            finalize_process(proc, stderr=b"".join(stderr_list))
+
+        handle_process_output(
+            proc, text_list.append, stderr_list.append, finalize_process_with_stderr, decode_streams=False
+        )
 
         # For now, we have to bake the stream.
         text = b"".join(text_list)
@@ -765,11 +775,16 @@ class Diff:
         # :100644 100644 687099101... 37c5e30c8... M    .gitignore
 
         index: "DiffIndex" = DiffIndex()
+        stderr_list: List[bytes] = []
+
+        def finalize_process_with_stderr(proc: Union["Popen", "Git.AutoInterrupt"]) -> None:
+            finalize_process(proc, stderr=b"".join(stderr_list))
+
         handle_process_output(
             proc,
             lambda byt: cls._handle_diff_line(byt, repo, index),
-            None,
-            finalize_process,
+            stderr_list.append,
+            finalize_process_with_stderr,
             decode_streams=False,
         )
 

{gitpython-3.1.48 → gitpython-3.1.52}/git/index/base.py

@@ -1480,12 +1480,11 @@ class IndexFile(LazyMixin, git_diff.Diffable, Serializable):
 
         return self
 
-    # FIXME: This is documented to accept the same parameters as Diffable.diff, but this
-    # does not handle NULL_TREE for `other`. (The suppressed mypy error is about this.)
     def diff(
         self,
-        other: Union[  # type: ignore[override]
+        other: Union[
             Literal[git_diff.DiffConstants.INDEX],
+            Literal[git_diff.DiffConstants.NULL_TREE],
             "Tree",
             "Commit",
             str,
@@ -1512,6 +1511,44 @@ class IndexFile(LazyMixin, git_diff.Diffable, Serializable):
         if other is self.INDEX:
             return git_diff.DiffIndex()
 
+        if other == git_diff.NULL_TREE or other == git_diff.NULL_TREE_SHA:
+            args: List[Union[PathLike, str]] = [
+                "--cached",
+                git_diff.NULL_TREE_SHA,
+                "--abbrev=40",
+                "--full-index",
+            ]
+
+            if not any(x in kwargs for x in ("find_renames", "no_renames", "M")):
+                args.append("-M")
+
+            if create_patch:
+                args.append("-p")
+                args.append("--no-ext-diff")
+            else:
+                args.append("--raw")
+                args.append("-z")
+
+            args.append("--no-color")
+
+            if paths is not None and not isinstance(paths, (tuple, list)):
+                paths = [paths]
+
+            if paths:
+                args.append("--")
+                args.extend(paths)
+
+            kwargs["as_process"] = True
+            proc = self.repo.git.diff(*args, **kwargs)
+
+            diff_method = (
+                git_diff.Diff._index_from_patch_format if create_patch else git_diff.Diff._index_from_raw_format
+            )
+            index = diff_method(self.repo, proc)
+
+            proc.wait()
+            return index
+
         # Index against anything but None is a reverse diff with the respective item.
         # Handle existing -R flags properly.
         # Transform strings to the object so that we can call diff on it.

{gitpython-3.1.48 → gitpython-3.1.52}/git/objects/commit.py

@@ -86,6 +86,12 @@ class Commit(base.Object, TraversableIterableObj, Diffable, Serializable):
     # INVARIANTS
     default_encoding = "UTF-8"
 
+    # Options to :manpage:`git-rev-list(1)` that can overwrite files.
+    unsafe_git_rev_options = [
+        "--output",
+        "-o",
+    ]
+
     type: Literal["commit"] = "commit"
 
     __slots__ = (
@@ -302,6 +308,7 @@ class Commit(base.Object, TraversableIterableObj, Diffable, Serializable):
         repo: "Repo",
         rev: Union[str, "Commit", "SymbolicReference"],
         paths: Union[PathLike, Sequence[PathLike]] = "",
+        allow_unsafe_options: bool = False,
         **kwargs: Any,
     ) -> Iterator["Commit"]:
         R"""Find all commits matching the given criteria.
@@ -330,6 +337,11 @@ class Commit(base.Object, TraversableIterableObj, Diffable, Serializable):
             raise ValueError("--pretty cannot be used as parsing expects single sha's only")
         # END handle pretty
 
+        if not allow_unsafe_options:
+            Git.check_unsafe_options(
+                options=Git._option_candidates([rev], kwargs), unsafe_options=cls.unsafe_git_rev_options
+            )
+
         # Use -- in all cases, to prevent possibility of ambiguous arguments.
         # See https://github.com/gitpython-developers/GitPython/issues/264.
 
@@ -374,6 +386,11 @@ class Commit(base.Object, TraversableIterableObj, Diffable, Serializable):
         """Create a git stat from changes between this commit and its first parent
         or from all changes done if this is the very first commit.
 
+        :note:
+            If this commit is at the boundary of a shallow clone, this will
+            raise :exc:`~git.exc.GitCommandError`, since the parent object
+            was never fetched and only exists as a reference on this commit.
+
         :return:
             :class:`Stats`
         """