@@ -879,11 +879,19 @@ def execute(
879879 Specifies a timeout in seconds for the git command, after which the process
880880 should be killed. This will have no effect if `as_process` is set to True.
881881 It is set to None by default and will let the process run until the timeout
882- is explicitly specified. This feature is not supported on Windows. It's also
883- worth noting that `kill_after_timeout` uses SIGKILL, which can have negative
884- side effects on a repository. For example, stale locks in case of ``git gc``
885- could render the repository incapable of accepting changes until the lock is
886- manually removed.
882+ is explicitly specified. Uses of this feature should be carefully
883+ considered, due to the following limitations:
884+
885+ 1. This feature is not supported at all on Windows.
886+ 2. Effectiveness may vary by operating system. ``ps --ppid`` is used to
887+ enumerate child processes, which is available on most GNU/Linux systems
888+ but not most others.
889+ 3. Deeper descendants do not receive signals, though they may sometimes
890+ terminate as a consequence of their parent processes being killed.
891+ 4. `kill_after_timeout` uses ``SIGKILL``, which can have negative side
892+ effects on a repository. For example, stale locks in case of ``git gc``
893+ could render the repository incapable of accepting changes until the lock
894+ is manually removed.
887895
888896 :param with_stdout:
889897 If True, default True, we open stdout on the created process.