Step 1: running
The first thing you need to do is run emacs without any of your customizations. If you can reproduce the problem in vanilla Emacs, it may actually be a bug in Emacs itself. That's rare, but we rule it out as a first step.
If you start Emacs from the command line with the
-Q flag, i.e.,
emacs -Q, you'll get a bare or 'vanilla' emacs, with none of your local customizations loaded. Does your problem still occur? If so, skip down to "Providing a Bug Recipe".
Step 1b: what if the problem is with a package?
If your problem is specific to a particular package, then obviously you can't reproduce it without loading that package. But you want to load only the package concerned, not all of your configuration. To do that, run
emacs -Q again, and prepare a short script such as the following:
package1 with the name of the package you want to load. If you need to load multiple packages, modify the script accordingly:
To load this code, you can paste it into the
*scratch* buffer, and call
M-x eval-buffer. (or any buffer, as long as it doesn't have any other code in it!).
At this point, you've loaded the package(s), and just the package(s) you're testing. If you can reproduce the problem now, skip down to "Providing a Bug Recipe".
Step 2: Finding a Bug in your
You've now confirmed that the problem is coming from something in your configuration ("the call is coming from inside the house!"). Your configuration may be many thousands of lines long, and may load many different files. To find the problem, you'll do a binary search, commenting out half the code at a time to narrow things down.1
- Open your regular emacs,
emacs, without the
- Open your config file (usually
.emacs.d/init.el, if you can't find it try
C-h v user-init-file)
- Select the first half of the file:
C-space to set the mark, scroll down half-way to extend the region
- Comment out the selected region:
M-; and save the file
- Open a new
emacs (your test emacs), leaving the first emacs running. test emacs will read the reduced version of your config.
- Try to reproduce the problem in test emacs
- If you can't reproduce it, close test emacs, and in your original emacs
undo the comment with
C-/, and comment out half of the remaining code. Open a new test emacs and try again.
- If you can reproduce the problem, comment out half of the remaining code and see if the problem persists.
- Repeat this process until you find the smallest bit of your configuration necessary to reproduce the problem.
If your problem is with a specific package, you'll have to leave the code that loads that package uncommented, of course.
If your config file loads other files, you may end up extending your search into those files as well.
At this point, you may have found that the problem is due to just a line or two of code. You may even be able to fix it yourself. If so, congratulations, you've learned something! Otherwise, move along to step three.
Step 3: Providing a Bug Recipe
At this point, you should be able to provide a detailed bug recipe to post here. It should include:
- Your Emacs version (you can get this from Emacs with
- Your operating system (Windows #, Mac, Linux distribution)
- The version of the package your struggling with, if applicable
- The specific steps necessary to demonstrate the problem, including what you expect to happen, and what actually happens.
For example, I might post a question like this:
I'm having a problem with super-mode. When I use
M-x sm-compile-code, it makes a withdrawal from my PayPal account.
Steps to reproduce:
- open a new file with
C-x C-f my-code
- enter a line of code:
10 goto 10
I expect this to invoke the super-compiler and compile my program. Instead, I see a message in the minibuffer "$100 transfered from paypal to super-mode author"
GNU Emacs 184.108.40.206
Super-mode version 3.1415
1The Bug Hunter package might help you with this, (semi-)automatically bisecting your init file.