Permalink
Browse files

Improve documentation about debugging tools

  • Loading branch information...
tarsius committed Apr 17, 2017
1 parent 5d4dd56 commit 57d8d16398e130b4c645be6fc28ac79668d216da
Showing with 122 additions and 5 deletions.
  1. +51 −2 Documentation/magit.org
  2. +63 −2 Documentation/magit.texi
  3. +4 −0 ISSUE_TEMPLATE
  4. +2 −0 lisp/magit-utils.el
  5. +2 −1 lisp/magit.el
View
@@ -271,6 +271,9 @@ See [[*How to install the gitman info manual?]].
If you are completely new to Magit then see [[*Getting Started]].
If you run into problems, then please see the [[*FAQ]]. Also see the
[[*Debugging Tools]].
And last but not least please consider making a donation, to ensure
that I can keep working on Magit. See https://magit.vc/donations.
for various donation options.
@@ -1333,8 +1336,9 @@ one you think you are using.
- Key: M-x magit-version, magit-version
Shows the currently used versions of Magit, Git, and Emacs in the
echo area. Non-interactively this just returns the Magit version.
This command shows the currently used versions of Magit, Git, and
Emacs in the echo area. Non-interactively this just returns the
Magit version.
When the ~system-type~ is ~windows-nt~, then ~magit-git-executable~ is set
to an absolute path when Magit is first loaded. This is necessary
@@ -6404,6 +6408,8 @@ frequently *and recently* asked questions, i.e. questions that haven't
made it into the manual yet, see
https://github.com/magit/magit/wiki/FAQ.
Please also use the [[*Debugging Tools]].
** FAQ - How to ...?
*** How to show git's output?
@@ -6611,6 +6617,49 @@ can work around the problem by setting
~tramp-ssh-controlmaster-options~. Changing your DNS server (e.g. to
Google's ~8.8.8.8~) may also be sufficient to work around the issue.
* Debugging Tools
Magit and its dependencies provide a few debugging tools, and we
appreciate it very much if you use those tools before reporting an
issue. Please include all relevant output when reporting an
issue.
- Key: M-x magit-version, magit-version
This command shows the currently used versions of Magit, Git, and
Emacs in the echo area. Non-interactively this just returns the
Magit version.
- Key: M-x magit-emacs-Q-command, magit-emacs-Q-command
This command shows a debugging shell command in the echo area and
adds it to the kill ring. Paste that command into a shell an run
it.
This shell command starts ~emacs~ and in which only ~magit~ and its
dependencies are loaded. Neither your configuration nor other
installed packages are not loaded. This makes it easier to
determine whether some issue lays with Magit or something else.
- Key: M-x magit-debug-git-executable, magit-debug-git-executable
This command displays a buffer containing information about the
available and used ~git~ executable(s), and can be useful when
investigating ~exec-path~ issues.
Also see [[*Git Executable]].
- Key: M-x with-editor-debug, with-editor-debug
This command displays a buffer containing information about the
available and used ~git~ executable(s), and can be useful when
investigating why Magit (or rather ~with-editor~) cannot find an
appropriate ~emacsclient~ executable.
Also see [[info:with-editor#Debugging]].
Please also see the [[*FAQ]].
* Keystroke Index
:PROPERTIES:
:APPENDIX: t
View
@@ -67,6 +67,7 @@ General Public License for more details.
* Customizing::
* Plumbing::
* FAQ::
* Debugging Tools::
* Keystroke Index::
* Command Index::
* Function Index::
@@ -551,6 +552,9 @@ See @ref{How to install the gitman info manual?,How to install the gitman info m
If you are completely new to Magit then see @ref{Getting Started,Getting Started}.
If you run into problems, then please see the @ref{FAQ,FAQ}. Also see the
@ref{Debugging Tools,Debugging Tools}.
And last but not least please consider making a donation, to ensure
that I can keep working on Magit. See @uref{https://magit.vc/donations}.
for various donation options.
@@ -1841,8 +1845,9 @@ one you think you are using.
@cindex magit-version
@item @kbd{M-x magit-version} @tie{}@tie{}@tie{}@tie{}(@code{magit-version})
Shows the currently used versions of Magit, Git, and Emacs in the
echo area. Non-interactively this just returns the Magit version.
This command shows the currently used versions of Magit, Git, and
Emacs in the echo area. Non-interactively this just returns the
Magit version.
@end table
When the @code{system-type} is @code{windows-nt}, then @code{magit-git-executable} is set
@@ -8603,6 +8608,8 @@ frequently @strong{and recently} asked questions, i.e. questions that haven't
made it into the manual yet, see
@uref{https://github.com/magit/magit/wiki/FAQ}.
Please also use the @ref{Debugging Tools,Debugging Tools}.
@menu
* FAQ - How to @dots{}?::
* FAQ - Issues and Errors::
@@ -8854,6 +8861,60 @@ can work around the problem by setting
@code{tramp-ssh-controlmaster-options}. Changing your DNS server (e.g. to
Google's @code{8.8.8.8}) may also be sufficient to work around the issue.
@node Debugging Tools
@chapter Debugging Tools
Magit and its dependencies provide a few debugging tools, and we
appreciate it very much if you use those tools before reporting an
issue. Please include all relevant output when reporting an
issue.
@table @asis
@kindex M-x magit-version
@cindex magit-version
@item @kbd{M-x magit-version} @tie{}@tie{}@tie{}@tie{}(@code{magit-version})
This command shows the currently used versions of Magit, Git, and
Emacs in the echo area. Non-interactively this just returns the
Magit version.
@kindex M-x magit-emacs-Q-command
@cindex magit-emacs-Q-command
@item @kbd{M-x magit-emacs-Q-command} @tie{}@tie{}@tie{}@tie{}(@code{magit-emacs-Q-command})
This command shows a debugging shell command in the echo area and
adds it to the kill ring. Paste that command into a shell an run
it.
This shell command starts @code{emacs} and in which only @code{magit} and its
dependencies are loaded. Neither your configuration nor other
installed packages are not loaded. This makes it easier to
determine whether some issue lays with Magit or something else.
@kindex M-x magit-debug-git-executable
@cindex magit-debug-git-executable
@item @kbd{M-x magit-debug-git-executable} @tie{}@tie{}@tie{}@tie{}(@code{magit-debug-git-executable})
This command displays a buffer containing information about the
available and used @code{git} executable(s), and can be useful when
investigating @code{exec-path} issues.
Also see @ref{Git Executable,Git Executable}.
@kindex M-x with-editor-debug
@cindex with-editor-debug
@item @kbd{M-x with-editor-debug} @tie{}@tie{}@tie{}@tie{}(@code{with-editor-debug})
This command displays a buffer containing information about the
available and used @code{git} executable(s), and can be useful when
investigating why Magit (or rather @code{with-editor}) cannot find an
appropriate @code{emacsclient} executable.
Also see @ref{Debugging,,,with-editor,}.
@end table
Please also see the @ref{FAQ,FAQ}.
@node Keystroke Index
@appendix Keystroke Index
View
@@ -50,4 +50,8 @@ Finally, if that didn't work and you have installed Magit from Melpa, then run c
$ cd ~/.emacs.d/elpa/magit-N
$ emacs -Q --debug-init --eval '(setq debug-on-error t)' -L ../dash-N -L ../git-commit-N -L ../magit-popup-N -L ../with-editor-N -L . -l magit
More debugging tools are described in the manual [6].
[6]: https://magit.vc/manual/magit/Debugging-Tools.html
---- now delete this line and everything above ----
View
@@ -524,6 +524,8 @@ ACTION is a member of option `magit-slow-confirm'."
;;;###autoload
(defun magit-emacs-Q-command ()
"Show a shell command that runs an uncustomized Emacs with only Magit loaded.
See info node `(magit)Debugging Tools' for more information."
(interactive)
(let ((cmd (mapconcat
#'shell-quote-argument
View
@@ -959,7 +959,8 @@ and Emacs to it."
magit-version))
(defun magit-debug-git-executable ()
"Display a buffer with information about `magit-git-executable'."
"Display a buffer with information about `magit-git-executable'.
See info node `(magit)Debugging Tools' for more information."
(interactive)
(with-current-buffer (get-buffer-create "*magit-git-debug*")
(pop-to-buffer (current-buffer))

0 comments on commit 57d8d16

Please sign in to comment.