Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 86d0177

Browse filesBrowse files
ByronByron
authored
Merge pull request #1782 from EliahKagan/shell-doc
Pre-deprecate setting Git.USE_SHELL
2 parents 9bc7872 + 106bbe6 commit 86d0177
Copy full SHA for 86d0177

File tree

8 files changed

+74
-39
lines changed
Filter options

8 files changed

+74
-39
lines changed

‎git/cmd.py

Copy file name to clipboardExpand all lines: git/cmd.py
+26-9Lines changed: 26 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -273,23 +273,40 @@ def __setstate__(self, d: Dict[str, Any]) -> None:
273273

274274
# CONFIGURATION
275275

276-
git_exec_name = "git" # Default that should work on Linux and Windows.
276+
git_exec_name = "git"
277+
"""Default git command that should work on Linux, Windows, and other systems."""
277278

278-
# Enables debugging of GitPython's git commands.
279279
GIT_PYTHON_TRACE = os.environ.get("GIT_PYTHON_TRACE", False)
280+
"""Enables debugging of GitPython's git commands."""
280281

281-
# If True, a shell will be used when executing git commands.
282-
# This should only be desirable on Windows, see https://github.com/gitpython-developers/GitPython/pull/126
283-
# and check `git/test_repo.py:TestRepo.test_untracked_files()` TC for an example where it is required.
284-
# Override this value using `Git.USE_SHELL = True`.
285282
USE_SHELL = False
283+
"""If True, a shell will be used when executing git commands.
284+
285+
This exists to avoid breaking old code that may access it, but it is no longer
286+
needed and should rarely if ever be used. Prior to GitPython 2.0.8, it had a narrow
287+
purpose in suppressing console windows in graphical Windows applications. In 2.0.8
288+
and higher, it provides no benefit, as GitPython solves that problem more robustly
289+
and safely by using the ``CREATE_NO_WINDOW`` process creation flag on Windows.
290+
291+
Code that uses ``USE_SHELL = True`` or that passes ``shell=True`` to any GitPython
292+
functions should be updated to use the default value of ``False`` instead. ``True``
293+
is unsafe unless the effect of shell expansions is fully considered and accounted
294+
for, which is not possible under most circumstances.
295+
296+
See:
297+
- https://github.com/gitpython-developers/GitPython/commit/0d9390866f9ce42870d3116094cd49e0019a970a
298+
- https://learn.microsoft.com/en-us/windows/win32/procthread/process-creation-flags
299+
"""
286300

287-
# Provide the full path to the git executable. Otherwise it assumes git is in the path.
288301
_git_exec_env_var = "GIT_PYTHON_GIT_EXECUTABLE"
289302
_refresh_env_var = "GIT_PYTHON_REFRESH"
303+
290304
GIT_PYTHON_GIT_EXECUTABLE = None
291-
# Note that the git executable is actually found during the refresh step in
292-
# the top level __init__.
305+
"""Provide the full path to the git executable. Otherwise it assumes git is in the path.
306+
307+
Note that the git executable is actually found during the refresh step in
308+
the top level ``__init__``.
309+
"""
293310

294311
@classmethod
295312
def refresh(cls, path: Union[None, PathLike] = None) -> bool:

‎git/config.py

Copy file name to clipboardExpand all lines: git/config.py
+12-8Lines changed: 12 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -65,12 +65,14 @@
6565
log.addHandler(logging.NullHandler())
6666

6767

68-
# The configuration level of a configuration file.
6968
CONFIG_LEVELS: ConfigLevels_Tup = ("system", "user", "global", "repository")
69+
"""The configuration level of a configuration file."""
7070

71-
# Section pattern to detect conditional includes.
72-
# https://git-scm.com/docs/git-config#_conditional_includes
7371
CONDITIONAL_INCLUDE_REGEXP = re.compile(r"(?<=includeIf )\"(gitdir|gitdir/i|onbranch):(.+)\"")
72+
"""Section pattern to detect conditional includes.
73+
74+
See: https://git-scm.com/docs/git-config#_conditional_includes
75+
"""
7476

7577

7678
class MetaParserBuilder(abc.ABCMeta): # noqa: B024
@@ -283,12 +285,14 @@ class GitConfigParser(cp.RawConfigParser, metaclass=MetaParserBuilder):
283285
"""
284286

285287
# { Configuration
286-
# The lock type determines the type of lock to use in new configuration readers.
287-
# They must be compatible to the LockFile interface.
288-
# A suitable alternative would be the BlockingLockFile
289288
t_lock = LockFile
290-
re_comment = re.compile(r"^\s*[#;]")
289+
"""The lock type determines the type of lock to use in new configuration readers.
291290
291+
They must be compatible to the LockFile interface.
292+
A suitable alternative would be the :class:`~git.util.BlockingLockFile`.
293+
"""
294+
295+
re_comment = re.compile(r"^\s*[#;]")
292296
# } END configuration
293297

294298
optvalueonly_source = r"\s*(?P<option>[^:=\s][^:=]*)"
@@ -299,8 +303,8 @@ class GitConfigParser(cp.RawConfigParser, metaclass=MetaParserBuilder):
299303

300304
del optvalueonly_source
301305

302-
# list of RawConfigParser methods able to change the instance
303306
_mutating_methods_ = ("add_section", "remove_section", "remove_option", "set")
307+
"""List of RawConfigParser methods able to change the instance."""
304308

305309
def __init__(
306310
self,

‎git/diff.py

Copy file name to clipboardExpand all lines: git/diff.py
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,8 +49,8 @@
4949

5050
__all__ = ("Diffable", "DiffIndex", "Diff", "NULL_TREE")
5151

52-
# Special object to compare against the empty tree in diffs.
5352
NULL_TREE = object()
53+
"""Special object to compare against the empty tree in diffs."""
5454

5555
_octal_byte_re = re.compile(rb"\\([0-9]{3})")
5656

‎git/index/base.py

Copy file name to clipboardExpand all lines: git/index/base.py
+4-2Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -142,9 +142,11 @@ class IndexFile(LazyMixin, git_diff.Diffable, Serializable):
142142

143143
__slots__ = ("repo", "version", "entries", "_extension_data", "_file_path")
144144

145-
_VERSION = 2 # Latest version we support.
145+
_VERSION = 2
146+
"""The latest version we support."""
146147

147-
S_IFGITLINK = S_IFGITLINK # A submodule.
148+
S_IFGITLINK = S_IFGITLINK
149+
"""Flags for a submodule."""
148150

149151
def __init__(self, repo: "Repo", file_path: Union[PathLike, None] = None) -> None:
150152
"""Initialize this Index instance, optionally from the given ``file_path``.

‎git/index/fun.py

Copy file name to clipboardExpand all lines: git/index/fun.py
+3-1Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,9 @@
4949
# ------------------------------------------------------------------------------------
5050

5151

52-
S_IFGITLINK = S_IFLNK | S_IFDIR # A submodule.
52+
S_IFGITLINK = S_IFLNK | S_IFDIR
53+
"""Flags for a submodule."""
54+
5355
CE_NAMEMASK_INV = ~CE_NAMEMASK
5456

5557
__all__ = (

‎git/objects/submodule/base.py

Copy file name to clipboardExpand all lines: git/objects/submodule/base.py
+6-5Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -77,9 +77,9 @@ class UpdateProgress(RemoteProgress):
7777
UPDWKTREE = UpdateProgress.UPDWKTREE
7878

7979

80-
# IndexObject comes via util module, its a 'hacky' fix thanks to pythons import
81-
# mechanism which cause plenty of trouble of the only reason for packages and
82-
# modules is refactoring - subpackages shouldn't depend on parent packages
80+
# IndexObject comes via the util module. It's a 'hacky' fix thanks to Python's import
81+
# mechanism, which causes plenty of trouble if the only reason for packages and
82+
# modules is refactoring - subpackages shouldn't depend on parent packages.
8383
class Submodule(IndexObject, TraversableIterableObj):
8484
"""Implements access to a git submodule. They are special in that their sha
8585
represents a commit in the submodule's repository which is to be checked out
@@ -95,10 +95,11 @@ class Submodule(IndexObject, TraversableIterableObj):
9595
k_modules_file = ".gitmodules"
9696
k_head_option = "branch"
9797
k_head_default = "master"
98-
k_default_mode = stat.S_IFDIR | stat.S_IFLNK # Submodules are directories with link-status.
98+
k_default_mode = stat.S_IFDIR | stat.S_IFLNK
99+
"""Submodule flags. Submodules are directories with link-status."""
99100

100-
# This is a bogus type for base class compatibility.
101101
type: Literal["submodule"] = "submodule" # type: ignore
102+
"""This is a bogus type for base class compatibility."""
102103

103104
__slots__ = ("_parent_commit", "_url", "_branch_path", "_name", "__weakref__")
104105

‎git/repo/base.py

Copy file name to clipboardExpand all lines: git/repo/base.py
+20-11Lines changed: 20 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -114,17 +114,18 @@ class Repo:
114114
'working_tree_dir' is the working tree directory, but will return None
115115
if we are a bare repository.
116116
117-
'git_dir' is the .git repository directory, which is always set."""
117+
'git_dir' is the .git repository directory, which is always set.
118+
"""
118119

119120
DAEMON_EXPORT_FILE = "git-daemon-export-ok"
120121

121-
git = cast("Git", None) # Must exist, or __del__ will fail in case we raise on `__init__()`
122+
git = cast("Git", None) # Must exist, or __del__ will fail in case we raise on `__init__()`.
122123
working_dir: PathLike
123124
_working_tree_dir: Optional[PathLike] = None
124125
git_dir: PathLike
125126
_common_dir: PathLike = ""
126127

127-
# precompiled regex
128+
# Precompiled regex
128129
re_whitespace = re.compile(r"\s+")
129130
re_hexsha_only = re.compile(r"^[0-9A-Fa-f]{40}$")
130131
re_hexsha_shortened = re.compile(r"^[0-9A-Fa-f]{4,40}$")
@@ -133,24 +134,32 @@ class Repo:
133134
re_tab_full_line = re.compile(r"^\t(.*)$")
134135

135136
unsafe_git_clone_options = [
136-
# This option allows users to execute arbitrary commands.
137-
# https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---upload-packltupload-packgt
137+
# Executes arbitrary commands:
138138
"--upload-pack",
139139
"-u",
140-
# Users can override configuration variables
141-
# like `protocol.allow` or `core.gitProxy` to execute arbitrary commands.
142-
# https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---configltkeygtltvaluegt
140+
# Can override configuration variables that execute arbitrary commands:
143141
"--config",
144142
"-c",
145143
]
144+
"""Options to ``git clone`` that allow arbitrary commands to be executed.
146145
147-
# invariants
148-
# represents the configuration level of a configuration file
146+
The ``--upload-pack``/``-u`` option allows users to execute arbitrary commands
147+
directly:
148+
https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---upload-packltupload-packgt
149+
150+
The ``--config``/``-c`` option allows users to override configuration variables like
151+
``protocol.allow`` and ``core.gitProxy`` to execute arbitrary commands:
152+
https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---configltkeygtltvaluegt
153+
"""
154+
155+
# Invariants
149156
config_level: ConfigLevels_Tup = ("system", "user", "global", "repository")
157+
"""Represents the configuration level of a configuration file."""
150158

151159
# Subclass configuration
152-
# Subclasses may easily bring in their own custom types by placing a constructor or type here
153160
GitCommandWrapperType = Git
161+
"""Subclasses may easily bring in their own custom types by placing a constructor or
162+
type here."""
154163

155164
def __init__(
156165
self,

‎git/util.py

Copy file name to clipboardExpand all lines: git/util.py
+2-2Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -557,8 +557,8 @@ class RemoteProgress:
557557
"_cur_line",
558558
"_seen_ops",
559559
"error_lines", # Lines that started with 'error:' or 'fatal:'.
560-
"other_lines",
561-
) # Lines not denoting progress (i.e.g. push-infos).
560+
"other_lines", # Lines not denoting progress (i.e.g. push-infos).
561+
)
562562
re_op_absolute = re.compile(r"(remote: )?([\w\s]+):\s+()(\d+)()(.*)")
563563
re_op_relative = re.compile(r"(remote: )?([\w\s]+):\s+(\d+)% \((\d+)/(\d+)\)(.*)")
564564

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.