dumb-jump

About

Dumb Jump is an Emacs "jump to definition" and "find references" package with support for 60+ 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 26.1.

Pre-Emacs 26 Support

Version 0.5.5 is the last release that supports Emacs versions below 26. If you need Emacs 24 or 25 support, use version 0.5.5 or earlier.

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 and you are using the legacy selector path, it will present the user with a list using completing-read, helm, or ivy via dumb-jump-selector. The xref UI is described separately later in this README.

Dumb Jump also supports find references -- the inverse of jump-to-definition. It finds where a symbol is used rather than where it is defined. This works by performing a broad symbol search and then filtering out results that match definition patterns, so it works for all 60+ supported languages with zero additional configuration.

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:

• Apex
• Bash
• C/C++
• C#
• Clojure
• COBOL
• CoffeeScript
• Common Lisp
• Coq
• Crystal
• D
• Dart
• Elixir
• Emacs Lisp
• Erlang
• F#
• Faust
• Fennel
• Fortran
• Go
• Groovy
• Haskell
• Jai
• Java
• JavaScript
• Julia
• Kotlin
• LaTeX
• Lua
• Matlab
• Nim
• Nix
• Objective-C
• OCaml
• Odin
• OpenSCAD
• Org mode
• Pascal
• Perl
• PHP
• Protocol Buffers
• PureScript
• Python
• R
• Racket
• Ruby
• Rust
• Sass
• Scala
• Scheme
• SML
• Solidity
• SQL
• Swift
• SystemVerilog
• Tcl
• Terraform / HCL
• TypeScript
• Vala
• VHDL
• Zig

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 (new in version 0.5.4), 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) to jump to definitions and <kbd>M-?</kbd> to find references.

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.

If you use Consult, you can set xref-show-definitions-function to consult-xref to get live preview of definition candidates while you cycle through them:

(setq xref-show-definitions-function #'consult-xref)

use-package example:

(use-package dumb-jump
  :ensure t
  :custom
  (dumb-jump-prefer-searcher 'rg)
  (xref-show-definitions-function #'consult-xref)
  :config
  (add-hook 'xref-backend-functions #'dumb-jump-xref-activate))

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 _FOSSIL_ Cargo.toml.

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 a searcher that can search outside the project root. The git-grep searcher cannot do this, so if you have explicitly set dumb-jump-force-searcher or dumb-jump-prefer-searcher to 'git-grep, switch to 'ag or 'rg instead (see below). The default automatic searcher selection (see the fallback order below) does not include git-grep, so this caveat only applies when git-grep has been explicitly configured.

.emacs options

• (setq dumb-jump-default-project "~/code") to change default project if one is not found (defaults to ~)
• (setq dumb-jump-quiet t) if Dumb Jump is too chatty.
• To support more languages and/or definition types customize dumb-jump-find-rules variable.
• (setq dumb-jump-git-grep-search-args "") to set additional command line arguments when using git-grep for searching (defaults to "").
• (setq dumb-jump-ag-search-args "") to set additional command line arguments when using ag for searching (defaults to "").
• (setq dumb-jump-rg-search-args "") to set additional command line arguments when using rg for searching (defaults to "--pcre2").

Two user-options are used to select the search tool:

• dumb-jump-prefer-searcher: identifies the search tool normally used, unless it is nil or the value of dumb-jump-force-searcher overrides your preference.
• dumb-jump-force-searcher: identifies how the searcher selection is overridden:
  • If you want to force a specific tool like ag or rg set dumb-jump-force-searcher to that value.
  • If you want to use the tool selected by dumb-jump-prefer-searcher except for some directories where you prefer to use git-grep, then set dumb-jump-force-searcher to a list holding the path of these directories.
  • If you want more flexibility in the overriding, then write a function that takes the project directory and return a symbol identifying the search tool to use for that project directory, or nil to honor dumb-jump-prefer-searcher choice.

When both dumb-jump-prefer-searcher and dumb-jump-force-searcher are nil, Dumb Jump selects the first tool found from this list, in that order:

• ag,
• rg,
• gnu grep,
• grep.

These can also all be set via Emacs customization. Once dumb-jump is loaded, type: <kbd>M-x</kbd> customize-group dumb-jump to open the customization buffer.

Here's a code example for using ag in most cases, but overriding this choice to rg in monorepos where git-grep has poor hit-rate, use git grep in some known directories like ~/src/emacs:

;; Choose a default searcher for most projects:
(setq dumb-jump-prefer-searcher 'ag)

;; Conditionally override the searcher per-project.
(defun my/dumb-jump-force-searcher (project-dir)
  "Return a dumb-jump searcher symbol for PROJECT-DIR, or nil to not override."
  (cond
   ;; Example: force ripgrep in monorepos where git-grep has poor hit-rate
   ;; (adapt the predicate to your environment).
   ((string-match-p "/work/monorepo-" project-dir) 'rg)

   ;; Example: force git-grep in a handful of projects where it’s known-good.
   ((member (file-truename project-dir)
            (mapcar #'file-truename
                    '("~/src/emacs/"
                      "~/src/small-lib/")))
    'git-grep)

   ;; Otherwise: no override; use dumb-jump-prefer-searcher selection.
   (t nil)))

(setq dumb-jump-force-searcher #'my/dumb-jump-force-searcher)

You can also force an overriding in a specific directory by setting dumb-jump-force-searcher in its .dir-locals.el file:

  ((nil . ((dumb-jump-force-searcher . rg))))

Overriding file extension to language mapping

Some file extensions are sh