README.md

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 (kbd "M-s"))

rg and friends is an autoloaded symbol so it's also possible to defer loading if you have autoloading setup.

wgrep

The default configuration of this package is compatible with wgrep. If grouped mode and/or show columns is enabled you need to install the wgrep-ag package from MELPA and configure it like this:

(add-hook 'rg-mode-hook 'wgrep-ag-setup)

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.

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")

The *rg* buffer

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

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")))

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:

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.

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.