Usage¶
Installation¶
This version of rg is supported on GNU Emacs 25.1 or later on Linux systems. It might work on older Emacsen and on other systems but such configurations are not tested. Patches for other OS:es are welcome.
MELPA
Packages are published on MELPA Stable and MELPA. From within Emacs,
run M-x package-install [RET] rg [RET]
to install from those
sources.
Enable default key bindings:
(rg-enable-default-bindings)
The above will enable the default key map under the default prefix
key C-c s
.
Manual
Releases can alternatively be downloaded from GitHub and installed
manually. Put all elisp files in main directory in your load path
and require
the package in your init file.
(require 'rg)
(rg-enable-default-bindings)
You would also need to make sure all package requirements are met. For this version these are:
- wgrep 2.1.10
- transient 0.1.0
- emacs 25.1
rg is using autoloaded symbols which means it’s also possible
to defer loading if you have autoloading setup. That usually comes
out of the box with package-install
.
Lazy loading
For lazy loading you don’t want to call directly into the package during startup. Use a setup similar to this instead:
(global-set-key (kbd "C-c s") #'rg-menu)
(with-eval-after-load 'rg
;; Your settings goes here.
)
If you don’t want to use the transient menu interface, the following is needed to achieve lazy loading:
;; Workaround for emacs' lack of autoloaded keymaps.
;; This is essentially what use-package do.
(defun rg-autoload-keymap ()
(interactive)
(if (not (require 'rg nil t))
(user-error (format "Cannot load rg"))
(let ((key-vec (this-command-keys-vector)))
(global-set-key key-vec rg-global-map)
(setq unread-command-events
(mapcar (lambda (ev) (cons t ev))
(listify-key-sequence key-vec))))))
(global-set-key (kbd "C-c s") #'rg-autoload-keymap)
(with-eval-after-load 'rg
;; Your settings goes here.
)
wgrep
This package use wgrep for editing capabilities in the rg results buffer. No setup is needed.
Interaction with the ripgrep configuration file
The ripgrep binary allows using a configuration file to set
default values for command line flags. This package requires
specific command line flags to function correctly and using a
ripgrep configuration may conflict with these requirements. Therefore
the configuration file is ignored by default. This can be changed
by the rg-ignore-ripgreprc
setting.
Note
Using the ripgrep configuration file may break functionality of this package if you are not careful.
Searching¶
Searching is done by invoking one of the different frontend commands. This package is built around recursive search based on three parameters; a single directory, file type filter, and a search pattern. These three parameters can interactively be selected or figured out automatically by the package, depending on which command that is used.
The underlying ripgrep binary has the file type filter concept built in. You have a high level of control over which files to search and which to ignore. This is partly what makes it so fast, ignoring uninteresting files.
In addition to the base parameters there are a lot of options that control how a search is done. These are typically selected from the rg-menu interface.
Case sensitivity¶
Considering case when searching is an important feature of any
search tool. This package gives you a lot of control over how to
handle case sensitive and case insensitive search. It can be
forced to on or off and set to smart case. The latter is
similar to the ripgrep --smart-case
flag but is not using the
flag directly. One thing to note about this is that the case
insensitive setting controls the behavior when starting a new
search. In the results buffer the setting is fixed to on or
off but can be toggled easily with a key binding. See
rg-ignore-case
customization for the details of the configuration.
Interactive search¶
Two commands implements fully interactive search, where all the base parameters are selected from the mini buffer.
-
C-c s r (rg)
¶ This command prompts for query, file type and directory and tries to suggest reasonable default values. The query string is interpreted as a regular expression. Default for query is the thing at point and for directory it is the current directory. If the type of the currently visited file is recognized, the corresponding file type alias is suggested as the file type parameter.
Invoking this command with the universal argument will trigger confirmation and potential modification of the full command line that will invoke the ripgrep binary.
-
C-c s t (rg-literal)
¶ This command works in the same way as
rg
but interprets the query string literally and not as a regular expression.Invoking this command with the universal argument will trigger confirmation and potential modification of the full command line that will invoke the ripgrep binary.
Project search¶
A common scenario is to search through a whole project while
visiting a file in the project. This essentially means identifying
the project root and use that as the top directory when invoking
the ripgrep binary. rg supports several ways of identifying a
project. Emacs’ major project packages are supported including
projectile, find-file-in-project and builtin project.el. If
none of these are used, the fallback is Emacs’ vc-backend
.
-
C-c s p (rg-project)
¶ Search in the current project. The directory is selected via one of Emacs’ project packages while query string and file type are prompted for. The query string is interpreted as a regular expression.
Do what I mean¶
The DWIM family of search commands tries to be smart by figure out the search parameters from the context without prompting. Thanks to ripgrep’s speed, this allows for new ways of searching by invoking a dwim command and then refine the search from the results buffer.
These commands use the word (with the definition of word depending
on context) under cursor as the query string. The file type
parameter is taken from the type of the currently visited file. If
the current file type can not be identified all file types known
to ripgrep are used. The fallback can be customized with
rg-default-alias-fallback
. The directory parameter varies
between these commands.
-
M-x rg-dwim-current-dir
¶ Do a DWIM search in the current directory.
-
M-x rg-dwim-current-file
¶ Do a DWIM search in the current file. The current file in this context is actually a file pattern exactly matching the current file name in a search starting from current directory. Most of the time this means a single file but if there are multiple files with the same name in a sub directory, those will be searched as well.
-
C-c s d (rg-dwim)
¶ This command combines all the DWIM commands to one. The default search is in the
project dir
. With one universal argumentcurrent directory
is used and with double universal arguments afile search
is done.
File type aliases¶
File type aliases are used in ripgrep to filter out the files
to search in. The ripgrep binary comes with a default set
of aliases that can be extended or overridden from this package by
customizing rg-custom-type-aliases
.
An alias is a mapping between a name and a list of glob patterns matching the files of interest. Selecting an alias when searching is done with completing read of the defined aliases. It is also possible to enter a custom glob pattern if there is no suitable alias defined for the file type.
rg defines some internal aliases:
Name | Meaning |
---|---|
all | all defined types including rg-custom-type-aliases |
everything | all files. No filtering on type is done. |
custom | used internally in this package for mapping custom glob patterns. |
Warning
Do not use any of the internal aliases in rg-custom-type-aliases
.
That would interfere with the package internal usage.
Results buffer¶
The results of a search is shown in the results buffer. This buffer displays search parameters, the full command line and the output of the ripgrep binary. It supports basic navigation between search results editing of the file contents directly from the search buffer and also modification of the current search. The results buffer is a modified compilation buffer and some key bindings and functionality is inherited from the parent and from grep mode.
Refine search¶
From the results buffer it’s easy to change the search parameters. Some bindings toggle a flag while others allow you to interactively change the base parameters.
-
d (rg-rerun-change-dir)
¶ Interactively change search directory.
-
f (rg-rerun-change-files)
¶ Interactively change searched file types.
-
t (rg-rerun-change-literal)
¶ Interactively change search string interpret the string literally.
-
r (rg-rerun-change-regexp)
¶ Interactively change search string interpret the string as a regular expression.
Tip
rg-rerun-change-regexp
and rg-rerun-change-literal
are
used for switching between regular expression and literal
search. So for quick switching between search modes with the same
search string, just press the respective key and then RET
.
-
g (rg-recompile)
¶ Rerun the current search without changing any parameters.
-
c (rg-rerun-toggle-case)
¶ Toggle case sensitivity of search. The state of the flag is shown in the [case] header field.
-
i (rg-rerun-toggle-ignore)
¶ Toggle if ignore files are respected. The state of the flag is shown in the [ign] header field.
Tip
It is possible to create and bind your own toggle flags with the
macro rg-define-toggle
.
Fire up the menu for full access to options and flags.
Full command line search¶
Some search commands (See rg
or rg-literal
) allow you to
edit the final command line before invoking the search by giving a
universal argument. This can be used to invoke features of the
ripgrep binary that is not supported in this package’s
interface. This could be specific flags, searching in multiple
directories etc.
Note
Using full command line search will disable refinement of the search from the result buffer.
Edit and apply (wgrep)¶
The results buffer supports inline editing via the wgrep package. This is setup automatically when rg is loaded.
-
e (wgrep-change-to-wgrep-mode)
¶ Make the search results editable by enabling
wgrep
mode. When done pressC-c C-c
to commit your changes to the underlying files orC-c C-k
to drop the changes.
Search management¶
The result buffer is named *rg*
and rg reuse the same result buffer for new
searches. If you want to store a search while continuing doing new searches
there are two ways of doing that.
-
s (rg-save-search)
¶ Save the search buffer by renaming it to a unique new name. This is available both outside and inside a result buffer. Outside of the result buffer it’s bound to
C-c s s
.If you want to keep all search buffers until manually killed you can use this snippet in your init file.
(defadvice rg-run (before rg-run-before activate) (rg-save-search))
-
S (rg-save-search-as-name)
¶ Save the search buffer and interactively give it a specific name. This is available both outside and inside a result buffer. Outside of the result buffer it’s bound to
C-c s S
.
The default buffer name can be customized with rg-buffer-name
. This
setting considers dir local variables and it’s even possible to use
a function to get a really dynamic setup.
Having a lot of search buffers floating around can easily get
messy. To help keeping this under control there is a search
manager. The manager is simply a modified ibuffer
that lists all
the results buffers, shows some data about the searches and make it
possible to kill of some unused etc.
-
L (rg-list-searches)
¶ Open the search manager. This is available both in result buffer and globally bound to
C-c s l
.
-
C-c s k (rg-kill-saved-searches)
¶ Kill all saved searches except for the one that matches
rg-buffer-name
. This is available both in result buffer and globally bound toC-c s k
.
Warning
If you have a dynamic rg-buffer-name
setup, only one buffer that
matches your current criteria (dir locals or project for instance)
will be kept. So be careful when killing saved searches to avoid
losing important search results.