Home

Awesome

dumb-jump

CI Coverage Status MELPA MELPA Stable

Dumb Jump GIF

About

Dumb Jump is an Emacs "jump to definition" package with support for 50+ programming languages that favors "just working". This means minimal -- and ideally zero -- configuration with absolutely no stored indexes (TAGS) or persistent background processes. Dumb Jump requires at least GNU Emacs 24.3.

How it works

Dumb Jump uses The Silver Searcher ag, ripgrep rg, or grep to find potential definitions of a function or variable under point. It uses a set of regular expressions based on the file extension, or major-mode, of the current buffer. The matches are run through a shared set of heuristic methods to find the best candidate to jump to. If it can't decide it will present the user with a list in a pop-menu, helm, or ivy (see dumb-jump-selector).

Success Rate

For the currently supported languages it seems to do a good job of finding what you want. If you find a case where it does not work as expected do not hesitate to open an issue. It can be slow if it needs to use grep and/or a project is large. Although it can be sped up by installing ag or installing rg and/or creating a .dumbjump file in your project's root directory with paths that should be excluded (see configuration).

Supported Languages

There is currently basic support for the following languages:

If you have any issues with the existing languages, or you want support for another one, then please open an issue. PRs are also welcome. If you'd like to add a language these PRs for lua and rust are good examples.

Installing

The recommended way to install Dumb Jump is via package.el. It's available on MELPA: <kbd>M-x</kbd> package-install dumb-jump

Spacemacs

If you're using an up-to-date Spacemacs, then you already have Dumb Jump by default just make sure you install ag or rg (see below) to ensure you have the best experience.

Installing ag or rg

Dumb Jump performs best with The Silver Searcher ag (ag install instructions) or ripgrep rg (rg install instructions) installed on your system.

Usage

Basic

To enable the xref backend, evaluate

(add-hook 'xref-backend-functions #'dumb-jump-xref-activate)

or add it to your initialisation file. Using this, you can now use <kbd>M-.</kbd> (or <kbd>gd</kbd> when using Evil).

Xref can be customized to use completing-read to select a target. That way a completion framework of your choice (Icomplete, Helm, Ivy, ...) will be used instead of the default pop-up buffer. To do this, evaluate

(setq xref-show-definitions-function #'xref-show-definitions-completing-read)

Note that the function xref-show-definitions-completing-read requires at least Xref 1.1.0. This can either be downloaded from ELPA or is bundled with Emacs 28.1 or newer.

Configuration

Excluding project directories

Dumb Jump will automatically look for a project root. If it's not finding one then either put a .dumbjump file in your project root and optionally add excluded directories to make it faster.

Project root directory denoters: .dumbjump .projectile .git .hg .fslckout .bzr _darcs .svn Makefile PkgInfo -pkg.el.

If you want to stop a directory from registering as the project root (and have Dumb Jump keep looking) add an empty .dumbjumpignore file in that directory.

Example .dumbjump
-tests
-node_modules
-build
-images
+../some-lib/src
+/usr/lib/src

NOTE When adding paths outside of the project (using +) ensure you use dumb-jump-force-searcher of either 'ag or 'rg (see below). This is required because the default searcher (git-grep) won't be able to search outside of the project root. This edge case will be fixed in a future release. That is, git-grep will NOT be set as the default searcher if a .dumbjump is present with a + path outside of the repo.

.emacs options

If your project has multi-line method signatures you should use ag or rg version 0.10.0 or higher.

To learn more about how Dumb Jump picks a searcher see this issue and this pull request.

Hydra for effieciency

If you have Hydra installed, the following is an example hydra for easily using Dumb-Jump and not needing to remember the bindings or function names:

(defhydra dumb-jump-hydra (:color blue :columns 3)
    "Dumb Jump"
    ("j" dumb-jump-go "Go")
    ("o" dumb-jump-go-other-window "Other window")
    ("e" dumb-jump-go-prefer-external "Go external")
    ("x" dumb-jump-go-prefer-external-other-window "Go external other window")
    ("i" dumb-jump-go-prompt "Prompt")
    ("l" dumb-jump-quick-look "Quick look")
    ("b" dumb-jump-back "Back"))

It can be explicitly bound or used inside another hydra (if you already use something like Avy/Ace or similar for general "jumping").

Debugging a jump

  1. <kbd>M-x</kbd> set-variable dumb-jump-debug t
  2. try to jump
  3. go to buffer *Messages*

More details here. Thanks to @cweiske and @Glumanda99

Obsolete commands and options

Older versions of dumb jump didn't use xref, and instead had custom commands. These, while marked obsolete, can still be used:

A few user options only have an effect when used with the legacy interface. These are:

The minor mode dumb-jump-mode binds a few of these commands by default.

If you still use Emacs 24 or older, you won't have xref, and have to use the legacy interface instead. In that case, there will also be no "obsolete" warnings.

Why?

I wanted "jump to definition" functionality to "just work" in emacs. I use IntelliJ for Java and this functionality is basically the only thing I miss when I switch back to emacs for work in other languages. There are certainly other packages that offer this type of functionality, but they all require significantly more configuration and are often limited to a particular language. An alternative may be worth setting up if you are in a specific project or language often (see alternatives).

Contributing

Feedback is very welcome via GitHub issues. I will consider supporting other languages either via issue request or PR. If submitting a PR then please add tests as well.

Running Tests

Opening a PR will use CircleCI to run all the tests against all the supported emacs versions and search programs.

Running tests locally

There are a lot of options for running the tests locally:

Basic/Classic

requires Cask using your local emacs

cd /path/to/dumb-jump
cask
make test

Concurrent

requires golang and Cask using your local emacs

cd /path/to/dumb-jump
cask
make test-concurrent

Docker (latest emacs)

only requires docker and runs tests against emacs 26.1

cd /path/to/dumb-jump
cask
make test-in-docker

Docker (all supported emacs versions)

only requires docker and runs tests against all supported emacs versions

cd /path/to/dumb-jump
cask
make test-all-in-docker

Alternatives

Here is a list of potential alternative packages for emacs:

Most of these were sourced from this emacs StackExchange answer.