[nongnu] elpa/git-commit 7353010 2/2: magit-git-debug, magit-process-extreme-logging: Improve documentation

[ELPA Syncer]

branch: elpa/git-commit
commit 73530108957c1167e155df9658d843c3bac0d9c7
Author: Jonas Bernoulli <jonas@bernoul.li>
Commit: Jonas Bernoulli <jonas@bernoul.li>

    magit-git-debug, magit-process-extreme-logging: Improve documentation
---
 Documentation/magit.org  | 35 +++++++++++++++++++++++++++++------
 Documentation/magit.texi | 38 +++++++++++++++++++++++++++++++-------
 lisp/magit-git.el        |  3 ++-
 lisp/magit-process.el    |  7 +++++--
 4 files changed, 67 insertions(+), 16 deletions(-)

diff --git a/Documentation/magit.org b/Documentation/magit.org
index 01251e3..7e5b8e7 100644
--- a/Documentation/magit.org
+++ b/Documentation/magit.org
@@ -8,7 +8,7 @@
 #+TEXINFO_DIR_CATEGORY: Emacs
 #+TEXINFO_DIR_TITLE: Magit: (magit).
 #+TEXINFO_DIR_DESC: Using Git from Emacs with Magit.
-#+SUBTITLE: for version 3.2.1 (v3.2.1-61-ge404aa75a+1)
+#+SUBTITLE: for version 3.2.1 (v3.2.1-62-g5a8e3aec3+1)
 
 #+TEXINFO_DEFFN: t
 #+OPTIONS: H:4 num:3 toc:2
@@ -25,7 +25,7 @@ directly from within Emacs.  While many fine Git clients 
exist, only
 Magit and Git itself deserve to be called porcelains.
 
 #+TEXINFO: @noindent
-This manual is for Magit version 3.2.1 (v3.2.1-61-ge404aa75a+1).
+This manual is for Magit version 3.2.1 (v3.2.1-62-g5a8e3aec3+1).
 
 #+BEGIN_QUOTE
 Copyright (C) 2015-2021 Jonas Bernoulli <jonas@bernoul.li>
@@ -1816,11 +1816,34 @@ sections are available.  There is one additional 
command.
 
   This command kills the process represented by the section at point.
 
-- User Option: magit-git-debug
+- Variable: magit-git-debug
+
+  This option controls whether additional reporting of git errors is
+  enabled.
+
+  Magit basically calls git for one of these two reasons: for
+  side-effects or to do something with its standard output.
+
+  When git is run for side-effects then its output, including error
+  messages, go into the process buffer which is shown when using ~$~.
+
+  When git's output is consumed in some way, then it would be too
+  expensive to also insert it into this buffer, but when this
+  option is non-nil and git returns with a non-zero exit status,
+  then at least its standard error is inserted into this buffer.
+
+  This is only intended for debugging purposes.  Do not enable this
+  permanently, that would negatively affect performance.
+
+- Variable: magit-process-extreme-logging
+
+  This option controls whether ~magit-process-file~ logs to the
+  ~*Messages*~ buffer.
 
-  When this is non-nil then the output of all calls to git are logged
-  in the process buffer.  This is useful when debugging, otherwise it
-  just negatively affects performance.
+  Only intended for temporary use when you try to figure out how
+  Magit uses Git behind the scene.  Output that normally goes to
+  the magit-process buffer continues to go there.  Not all output
+  goes to either of these two buffers.
 
 *** Git Process Status
 
diff --git a/Documentation/magit.texi b/Documentation/magit.texi
index 5d5bd8c..64cd9a5 100644
--- a/Documentation/magit.texi
+++ b/Documentation/magit.texi
@@ -31,7 +31,7 @@ General Public License for more details.
 @finalout
 @titlepage
 @title Magit User Manual
-@subtitle for version 3.2.1 (v3.2.1-61-ge404aa75a+1)
+@subtitle for version 3.2.1 (v3.2.1-62-g5a8e3aec3+1)
 @author Jonas Bernoulli
 @page
 @vskip 0pt plus 1filll
@@ -53,7 +53,7 @@ directly from within Emacs.  While many fine Git clients 
exist, only
 Magit and Git itself deserve to be called porcelains.
 
 @noindent
-This manual is for Magit version 3.2.1 (v3.2.1-61-ge404aa75a+1).
+This manual is for Magit version 3.2.1 (v3.2.1-62-g5a8e3aec3+1).
 
 @quotation
 Copyright (C) 2015-2021 Jonas Bernoulli <jonas@@bernoul.li>
@@ -2485,12 +2485,36 @@ This command kills the process represented by the 
section at point.
 
 @end table
 
-@defopt magit-git-debug
+@defvar magit-git-debug
 
-When this is non-nil then the output of all calls to git are logged
-in the process buffer.  This is useful when debugging, otherwise it
-just negatively affects performance.
-@end defopt
+This option controls whether additional reporting of git errors is
+enabled.
+
+Magit basically calls git for one of these two reasons: for
+side-effects or to do something with its standard output.
+
+When git is run for side-effects then its output, including error
+messages, go into the process buffer which is shown when using @code{$}.
+
+When git's output is consumed in some way, then it would be too
+expensive to also insert it into this buffer, but when this
+option is non-nil and git returns with a non-zero exit status,
+then at least its standard error is inserted into this buffer.
+
+This is only intended for debugging purposes.  Do not enable this
+permanently, that would negatively affect performance.
+@end defvar
+
+@defvar magit-process-extreme-logging
+
+This option controls whether @code{magit-process-file} logs to the
+@code{*Messages*} buffer.
+
+Only intended for temporary use when you try to figure out how
+Magit uses Git behind the scene.  Output that normally goes to
+the magit-process buffer continues to go there.  Not all output
+goes to either of these two buffers.
+@end defvar
 
 @node Git Process Status
 @subsection Git Process Status
diff --git a/lisp/magit-git.el b/lisp/magit-git.el
index 3a02767..84a6c51 100644
--- a/lisp/magit-git.el
+++ b/lisp/magit-git.el
@@ -222,8 +222,9 @@ option is non-nil and git returns with a non-zero exit 
status,
 then at least its standard error is inserted into this buffer.
 
 This is only intended for debugging purposes.  Do not enable this
-permanently, that would negatively affect performance.")
+permanently, that would negatively affect performance.
 
+Also see `magit-process-extreme-logging'.")
 
 (defcustom magit-prefer-remote-upstream nil
   "Whether to favor remote branches when reading the upstream branch.
diff --git a/lisp/magit-process.el b/lisp/magit-process.el
index 0da5679..953b2a5 100644
--- a/lisp/magit-process.el
+++ b/lisp/magit-process.el
@@ -97,11 +97,14 @@ When this is nil, no sections are ever removed."
   :type '(choice (const :tag "Never remove old sections" nil) integer))
 
 (defvar magit-process-extreme-logging nil
-  "Whether `magit-process-file' logs to *Messages* buffer.
+  "Whether `magit-process-file' logs to the *Messages* buffer.
+
 Only intended for temporary use when you try to figure out how
 Magit uses Git behind the scene.  Output that normally goes to
 the magit-process buffer continues to go there.  Not all output
-goes to either of these two buffers.")
+goes to either of these two buffers.
+
+Also see `magit-git-debug'.")
 
 (defcustom magit-process-error-tooltip-max-lines 20
   "The number of lines for `magit-process-error-lines' to return.