wedens / rg.el

Emacs search tool based on ripgrep

rg.el

Use ripgrep in Emacs.

Ripgrep is a replacement for both grep like (search one file) and ag like (search many files) tools. It's fast and versatile and written in Rust. For some introduction and benchmarks, see ripgrep is faster than {grep, ag, git grep, ucg, pt, sift}.

This package let you run ripgrep like grep from within Emacs.

Installation

This package is available on MELPA Stable and MELPA. Install with M-x package-install RET rg from within Emacs.

If you want to install manually just put rg.el somewhere in your load path and add this to init.el

(require 'rg)
(rg-enable-default-bindings)

rg and friends are autoloaded symbols which means it's also possible to defer loading if you have autoloading setup.

wgrep

This package use wgrep for doing changes to matched files from the rg results buffer. No setup is needed.

Usage

Main entry point - rg

Invoke by M-x rg. This works the same way as M-x rgrep, i.e. you get an interactive prompt to enter search details. Universal argument can be used as for rgrep.

Project search - rg-project

M-x rg-project searches in a project defined by projectile, find-file-in-project or a vc-backend.

Do what I mean - rg-dwim

M-x rg-dwim searches for thing at point in a project in all files with the same type alias as the current buffer file.

Literal search - rg-literal

M-x rg-literal is a non regexp version of rg.

Saving searches

A search result buffer can be saved by invoking rg-save-search or rg-save-search-as-name. The former will give the saved buffer a unique name and the latter will prompt the user for a name. The rg-list-searches command will open a buffer with all active rg-mode buffers showing basic information about each search.

Type aliases

ripgrep has its own built in mappings from type names to file name patterns that can be selected from rg.el on invocation of rg. It's also possible to specify a custom file name pattern in the files prompt.

There are some aliases with special meanings in rg.el.

Name	Meaning
all	all defined types including rg-custom-type-aliases
everything	all files, i.e. running rg without --type flag
custom	used internally in rg.el for mapping custom globs. Do not use this in rg-custom-type-aliases

Key bindings

This package comes with a set of predefined key bindings that can be enabled by calling rg-enable-default-bindings with an optional prefix key of choice. The default prefix is C-c s and can be customized with rg-keymap-prefix. It is also possible to set the prefix when invoking rg-enable-default-bindings.

(rg-enable-default-bindings "\M-s")

Key	Binding
<prefix> d	rg-dwim
<prefix> k	rg-kill-saved-searches
<prefix> l	rg-list-searches
<prefix> p	rg-project
<prefix> r	rg
<prefix> s	rg-save-search
<prefix> S	rg-save-search-as-name
<prefix> t	rg-literal

The *rg* buffer

The rg results buffer has bindings for modification of the last search for quick reruns with refined parameters.

Key	Description
c	Toggle case insensitive setting
d	Change directory
f	Change file pattern
g	Rerun search
i	Toggle --no-ignore flag
l	List search buffers in a separate buffer
r	Edit search string as regexp
s	Save search result to unique name
S	Save search result, prompt for name
t	Edit search string as literal
w	Switch to wgrep mode
C-f	Navigate forward in search history
C-b	Navigate backward in search history

History navigation

Search history is stored per result buffer. It's possible to navigate back and forward in earlier searches with rg-back-history and rg-forward-history. Whenever a search is modified or a new is created future searches are cleared.

Customize

rg-custom-type-aliases

Custom type patterns as for rgrep are supported via customizing of rg-custom-type-aliases.

(setq rg-custom-type-aliases
  '(("foo" .    "*.foo *.bar")
    ("baz" .    "*.baz *.qux")))

You may also add lambdas to rg-custom-type-aliases to add aliases dynamically based on mode, directory, project, etc.

 (add-to-list
  'rg-custom-type-aliases
  (lambda ()
    (when (in-frontend-app)
      (cons "ui" "*.js *.hbs *.json"))))

rg-command-line-flags

Additional command line flags that will be appended to the ripgrep command line. Must either be a list of flags or a function that returns a list of flags.

rg-group-result

Controls the layout of the results buffer. If non nil, each file name is displayed once and matches are grouped under that filename instead of repeating the filename on each match. This is essentially the layout of the --no-heading ripgrep command line flag. Default value is nil (off).

rg-show-columns

Controls if column numbers are used in the search result. Default value is nil (off).

rg-ignore-case

Variable that controls when case sensitive search is made or not. The following values can be set:

Symbol	Description
'case-fold-search	Smart search based on case-fold-search setting.
'smart	Smart search. Case sensitive if at least one character is uppercase, otherwise ignore case.
'force	Force ignore case.
nil	Always case sensitive search.

rg-hide-command

Hide most of command line by default. This is enabled by default and can be set to nil to show full command line by default.

rg-keymap-prefix

This variable sets the default prefix used for the global key bindings. Note that rg-enable-default-bindings needs to be invoked for the bindings to be enabled.

rg-show-header

Controls if the search info header is shown in the result buffer. This is enabled by default but can be disabled by setting this variable to nil.

Position numbers alignment

When operating rg.el in grouped output mode (rg-group-result is non nil), it's possible to control how the line and column numbers are displayed in the result buffer.

Example settings:

(setq rg-align-position-numbers t)
(setq rg-align-line-number-field-length 3)
(setq rg-align-column-number-field-length 3)
(setq rg-align-line-column-separator "#")
(setq rg-align-position-content-separator "|")

Will yield the following format:

File: matched_file.foo
  1#  2|match1
888# 10|match2

rg-align-position-numbers

Setting this to t will align line and column numbers in columns padded with whitespace.

rg-align-line-number-field-length

Defines the length of the line number field.

rg-align-column-number-field-length

Defines the length of the column number field.

rg-align-line-column-separator

Separator string used between line and column numbers.

rg-align-position-content-separator

Separator string used between the position numbers and matched content.

rg-define-toggle

This is a macro that can be used to define custom ripgrep flag toggling functions in the rg result buffer. The macro takes the flag (and potential value) as an argument and optionally binds the toggle function to a key and enable the flag by default.

The function defined by this macro will be named as the flag name stripped with leading dashes and prefixed with rg-custom-toggle-flag-.

(rg-define-toggle "-uu" "I" t)

Creates a function named rg-custom-toggle-flag-uu that is on by default and bound to I in rg result buffer.

(rg-define-toggle "--context 3" (kbd "C-c c"))

Creates a function named rg-custom-toggle-flag-context that is off by default and bound to C-c c in rg result buffer.

rg-define-search

This macro can be used to define custom search functions in a declarative style. Default implementations for common behavior is available and custom forms can also be used. See the package documentation for details.

Example:

(rg-define-search search-home-dir-in-elisp
  "Doc string."
  :query ask
  :format literal
  :files "elisp"
  :dir (getenv "HOME"))

Contribute

• Install cask.
• Install dependencies:

make deps

• Run tests:

make test

License

See LICENSE.