branch: elpa/magit
commit ee7a2499cfe5c1b09c52d468864cc44d5897a721
Author: Jonas Bernoulli <jo...@bernoul.li>
Commit: Jonas Bernoulli <jo...@bernoul.li>
magit-toggle-git-debug: Improve documentation
Focus on documenting the command `magit-toggle-git-debug', at the
expense of the documentation for the variable `magit-git-debug',
which users don't really have to know about.
---
docs/magit.org | 57 ++++++++++++++++++++++-----------------------------
docs/magit.texi | 61 ++++++++++++++++++++++++-------------------------------
lisp/magit-git.el | 32 ++++++++---------------------
3 files changed, 59 insertions(+), 91 deletions(-)
diff --git a/docs/magit.org b/docs/magit.org
index 72a4cac0317..0388715637e 100644
--- a/docs/magit.org
+++ b/docs/magit.org
@@ -1840,10 +1840,9 @@ sections are available. There is one additional command.
This command kills the process represented by the section at point.
-- Variable: magit-git-debug ::
+- Key: M-x magit-toggle-git-debug ::
- This option controls whether additional reporting of git errors is
- enabled.
+ This command toggles whether additional git errors are reported.
Magit basically calls git for one of these two reasons: for
side-effects or to do something with its standard output.
@@ -1852,24 +1851,17 @@ sections are available. There is one additional
command.
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.
-
- This is only intended for debugging purposes. Do not enable this
- permanently, that would negatively affect performance. Also note
- that just because git exits with a non-zero exit status and prints
- an error message that usually doesn't mean that it is an error as
- far as Magit is concerned, which is another reason we usually hide
- these error messages. Whether some error message is relevant in
- the context of some unexpected behavior has to be judged on a case
- by case basis.
-
- The command ~magit-toggle-git-debug~ changes the value of this
- variable.
+ expensive to also insert it into this buffer, but with this command
+ that can be enabled temporarily. In that case, if git returns with
+ a non-zero exit status, then at least its standard error is inserted
+ into this buffer.
+
+ Also note that just because git exits with a non-zero status and
+ prints an error message, that usually doesn't mean that it is an
+ error as far as Magit is concerned, which is another reason we
+ usually hide these error messages. Whether some error message is
+ relevant in the context of some unexpected behavior has to be judged
+ on a case by case basis.
- Variable: magit-process-extreme-logging ::
@@ -9338,18 +9330,17 @@ issue.
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. Also note
- that just because git exits with a non-zero exit status and prints
- an error message that usually doesn't mean that it is an error as
- far as Magit is concerned, which is another reason we usually hide
- these error messages. Whether some error message is relevant in
- the context of some unexpected behavior has to be judged on a case
- by case basis.
+ expensive to also insert it into this buffer, but with this command
+ that can be enabled temporarily. In that case, if git returns with
+ a non-zero exit status, then at least its standard error is inserted
+ into this buffer.
+
+ Also note that just because git exits with a non-zero status and
+ prints an error message, that usually doesn't mean that it is an
+ error as far as Magit is concerned, which is another reason we
+ usually hide these error messages. Whether some error message is
+ relevant in the context of some unexpected behavior has to be judged
+ on a case by case basis.
- Key: M-x magit-toggle-verbose-refresh ::
diff --git a/docs/magit.texi b/docs/magit.texi
index e9bd7ec3422..a9321ddad96 100644
--- a/docs/magit.texi
+++ b/docs/magit.texi
@@ -2374,11 +2374,10 @@ sections are available. There is one additional
command.
@kindex k
@findex magit-process-kill
This command kills the process represented by the section at point.
-@end table
-@defvar magit-git-debug
-This option controls whether additional reporting of git errors is
-enabled.
+@item @kbd{M-x magit-toggle-git-debug}
+@findex magit-toggle-git-debug
+This command toggles whether additional git errors are reported.
Magit basically calls git for one of these two reasons: for
side-effects or to do something with its standard output.
@@ -2387,25 +2386,18 @@ 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.
-
-This is only intended for debugging purposes. Do not enable this
-permanently, that would negatively affect performance. Also note
-that just because git exits with a non-zero exit status and prints
-an error message that usually doesn't mean that it is an error as
-far as Magit is concerned, which is another reason we usually hide
-these error messages. Whether some error message is relevant in
-the context of some unexpected behavior has to be judged on a case
-by case basis.
-
-The command @code{magit-toggle-git-debug} changes the value of this
-variable.
-@end defvar
+expensive to also insert it into this buffer, but with this command
+that can be enabled temporarily. In that case, if git returns with
+a non-zero exit status, then at least its standard error is inserted
+into this buffer.
+
+Also note that just because git exits with a non-zero status and
+prints an error message, that usually doesn't mean that it is an
+error as far as Magit is concerned, which is another reason we
+usually hide these error messages. Whether some error message is
+relevant in the context of some unexpected behavior has to be judged
+on a case by case basis.
+@end table
@defvar magit-process-extreme-logging
This option controls whether @code{magit-process-file} logs to the
@@ -11424,18 +11416,17 @@ 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. Also note
-that just because git exits with a non-zero exit status and prints
-an error message that usually doesn't mean that it is an error as
-far as Magit is concerned, which is another reason we usually hide
-these error messages. Whether some error message is relevant in
-the context of some unexpected behavior has to be judged on a case
-by case basis.
+expensive to also insert it into this buffer, but with this command
+that can be enabled temporarily. In that case, if git returns with
+a non-zero exit status, then at least its standard error is inserted
+into this buffer.
+
+Also note that just because git exits with a non-zero status and
+prints an error message, that usually doesn't mean that it is an
+error as far as Magit is concerned, which is another reason we
+usually hide these error messages. Whether some error message is
+relevant in the context of some unexpected behavior has to be judged
+on a case by case basis.
@item @kbd{M-x magit-toggle-verbose-refresh}
@findex magit-toggle-verbose-refresh
diff --git a/lisp/magit-git.el b/lisp/magit-git.el
index b396f21a390..d0afadc9831 100644
--- a/lisp/magit-git.el
+++ b/lisp/magit-git.el
@@ -225,37 +225,23 @@ framework ultimately determines how the collection is
displayed."
;;; Git
-(defvar magit-git-debug nil
- "Whether to enable additional reporting of git errors.
+(defvar magit-git-debug nil)
+
+(defun magit-toggle-git-debug ()
+ "Toggle whether additional git errors are reported.
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 \
-\\<magit-status-mode-map>\\[magit-process-buffer].
+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. Also note
-that just because git exits with a non-zero exit status and prints
-an error message that usually doesn't mean that it is an error as
-far as Magit is concerned, which is another reason we usually hide
-these error messages. Whether some error message is relevant in
-the context of some unexpected behavior has to be judged on a case
-by case basis.
+expensive to also insert it into this buffer, but with this command
+that can be enabled temporarily. In that case, if git returns with
+a non-zero exit status, then at least its standard error is inserted
+into this buffer.
-The command `magit-toggle-git-debug' changes the value of this
-variable.
-
-Also see `magit-process-extreme-logging'.")
-
-(defun magit-toggle-git-debug ()
- "Toggle whether additional git errors are reported.
See info node `(magit)Debugging Tools' for more information."
(interactive)
(setq magit-git-debug (not magit-git-debug))
