branch: elpa/git-commit
commit 73530108957c1167e155df9658d843c3bac0d9c7
Author: Jonas Bernoulli <jo...@bernoul.li>
Commit: Jonas Bernoulli <jo...@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 <jo...@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.
