Skip to content

Clarify Git.execute and Popen arguments #1688

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 11 commits into from
Oct 3, 2023
Prev Previous commit
Next Next commit
Copyedit Git.execute docstring
These are some small clarity and consistency revisions to the
docstring of git.cmd.Git.execute that didn't specifically fit in
the narrow topics of either of the preceding two commits.
  • Loading branch information
EliahKagan committed Oct 3, 2023
commit 74b68e9b621a729a3407b2020b0a48d7921fb1e9
25 changes: 12 additions & 13 deletions git/cmd.py
Original file line number Diff line number Diff line change
Expand Up @@ -851,7 +851,7 @@ def execute(
program to execute is the first item in the args sequence or string.

:param istream:
Standard input filehandle passed to subprocess.Popen.
Standard input filehandle passed to `subprocess.Popen`.

:param with_extended_output:
Whether to return a (status, stdout, stderr) tuple.
Expand All @@ -862,8 +862,7 @@ def execute(
:param as_process:
Whether to return the created process instance directly from which
streams can be read on demand. This will render with_extended_output and
with_exceptions ineffective - the caller will have
to deal with the details himself.
with_exceptions ineffective - the caller will have to deal with the details.
It is important to note that the process will be placed into an AutoInterrupt
wrapper that will interrupt the process once it goes out of scope. If you
use the command in iterators, you should pass the whole process instance
Expand All @@ -876,25 +875,25 @@ def execute(
always be created with a pipe due to issues with subprocess.
This merely is a workaround as data will be copied from the
output pipe to the given output stream directly.
Judging from the implementation, you shouldn't use this flag !
Judging from the implementation, you shouldn't use this parameter!

:param stdout_as_string:
if False, the commands standard output will be bytes. Otherwise, it will be
decoded into a string using the default encoding (usually utf-8).
If False, the command's standard output will be bytes. Otherwise, it will be
decoded into a string using the default encoding (usually UTF-8).
The latter can fail, if the output contains binary data.

:param kill_after_timeout:
To specify a timeout in seconds for the git command, after which the process
Specifies a timeout in seconds for the git command, after which the process
should be killed. This will have no effect if as_process is set to True. It is
set to None by default and will let the process run until the timeout is
explicitly specified. This feature is not supported on Windows. It's also worth
noting that kill_after_timeout uses SIGKILL, which can have negative side
effects on a repository. For example, stale locks in case of git gc could
effects on a repository. For example, stale locks in case of ``git gc`` could
render the repository incapable of accepting changes until the lock is manually
removed.

:param with_stdout:
If True, default True, we open stdout on the created process
If True, default True, we open stdout on the created process.

:param universal_newlines:
if True, pipes will be opened as text, and lines are split at
Expand All @@ -916,19 +915,19 @@ def execute(
Whether to strip the trailing ``\\n`` of the command stdout.

:param subprocess_kwargs:
Keyword arguments to be passed to subprocess.Popen. Please note that
some of the valid kwargs are already set by this method, the ones you
Keyword arguments to be passed to `subprocess.Popen`. Please note that
some of the valid kwargs are already set by this method; the ones you
specify may not be the same ones.

:return:
* str(output) if extended_output = False (Default)
* tuple(int(status), str(stdout), str(stderr)) if extended_output = True

if output_stream is True, the stdout value will be your output stream:
If output_stream is True, the stdout value will be your output stream:
* output_stream if extended_output = False
* tuple(int(status), output_stream, str(stderr)) if extended_output = True

Note git is executed with LC_MESSAGES="C" to ensure consistent
Note that git is executed with ``LC_MESSAGES="C"`` to ensure consistent
output regardless of system language.

:raise GitCommandError:
Expand Down