Troubleshooting

In case you run into issues here are a few tips that can help you diagnose the problem.

Generally, it’s not a bad idea to configure Emacs to spit the backtrace on error (instead of just logging the error in the *Messages* buffer). You can toggle this behavior by using M-x toggle-debug-on-error.

Debugging Projectile commands

Emacs features a super powerful built-in Emacs Lisp debugger and using it is the best way to diagnose problems of any kind.

Here’s a great crash course on using the debugger.

To debug some command you need to do the following:

  • Figure out the name of the command you want to debug (e.g. by using C-h k to see which command is associated with some keybinding)

  • Find the source of the command (e.g. by using M-x find-function RET function-name)

  • Press C-u C-M-x while in the body of the function

  • Run the command again

At this point you’ll be dropped in the debugger and you can step forward until you find the problem.

Profiling Projectile commands

Emacs comes with a built-in profiler. Using it is pretty simple:

  1. Start it with M-x profiler-start.

  2. Invoke some commands.

  3. Get the report with M-x profiler-report.

If you intend to share the profiling results with someone it’s a good idea to save the report buffer to a file with C-x C-w.

Commonly encountered problems (and how to solve them)

Using some command causes Emacs to freeze for a while

Sometimes a Projectile command might hang for a while (e.g. due to a bug or a configuration issue). Such problems are super annoying, but are relatively easy to debug. Here are a few steps you can take in such situations:

  • Do M-x toggle-debug-on-quit

  • Reproduce the problem

  • Hit C-g around 10 seconds into the hang

This will bring up a backtrace with the entire function stack, including function arguments. So you should be able to figure out what’s going on (or at least what’s being required).

I upgraded Projectile using package.el and nothing changed

Emacs doesn’t load the new files, it only installs them on disk. To see the effect of changes you have to restart Emacs.

Some commands not working properly with the fish shell

I’m not sure what’s causing this (likely different quoting rules), but it’s easy to fix it:

(setq shell-file-name "/bin/bash")

In general, I’ve noticed that Emacs doesn’t play very well with fish.