GNU ELPA - urgrep

urgrep Atom Feed

Universal recursive grep
urgrep-0.5.0.tar (.sig), 2024-May-12, 100 KiB
Browse ELPA's repository
CGit or Gitweb

To install this package from Emacs, use package-install or list-packages.

Full description

Urgrep - Universal Recursive Grep

GNU ELPA version

Urgrep is an Emacs package to provide a universal frontend for any grep-like tool, as an alternative to the built-in M-x rgrep (and other similar packages). Currently, ugrep, ripgrep, ag, ack, git grep, and grep/find are supported.

Why Urgrep?

One package, many tools

No matter which tool you prefer, you can use it with Urgrep. If a new tool comes along, you won't need to find a new Emacs package for it.

Rich minibuffer interface

Easily manipulate per-search options with Isearch-like key bindings within the Urgrep minibuffer prompt.

Seamless support for Tramp

Each host can use a different set of tools depending on what the system has installed without any special configuration.

Using Urgrep

The primary entry point to Urgrep is the interactive function urgrep. This prompts you for a query to search for in, by default, the root directory of the current project (or the default-directory if there is no project). By prefixing with C-u, this will always start the search within the default-directory. With C-u C-u, Urgrep will first prompt you for the search directory. Within the search prompt, there are several Isearch-like key bindings to let you modify the search's behavior:

Key binding Action
M-s h Describe key bindings
M-s r Toggle regexp search
M-s c Toggle case folding
M-s H Toggle searching in hidden files
M-s f Set wildcards to filter files¹
M-s C Set number of lines of context²
M-s B Set number of lines of leading context²
M-s A Set number of lines of trailing context²
M-s t Set the search tool
  1. Prompts with a recursive minibuffer
  2. With a numeric prefix argument, set immediately; otherwise, use a recursive minibuffer

In addition to the above, you can call urgrep-run-command, which works like urgrep but allows you to manually edit the command before executing it.

Modifying your search

After performing a search, you can adjust an existing query with C-u g, reopening the original search prompt. You can also adjust some of the search options, such as case folding, immediately:

Key binding Action
c Toggle case folding
H Toggle searching in hidden files
C Expand lines of context¹
B Expand lines of leading context¹
A Expand lines of trailing context¹
  1. Expand by one line by default, or by N lines with a prefix argument
Configuring the tool to use

By default, Urgrep tries all search tools it's aware of to find the best option. To improve performance, you can restrict the set of tools to search for by setting urgrep-preferred-tools:

elisp (setq urgrep-preferred-tools '(git-grep grep))

If a tool is installed in an unusual place on your system, you can specify this by providing a cons cell as an element in urgrep-preferred-tools:

elisp (setq urgrep-preferred-tools '((ag . "/home/coco/bin/ag")))

This also works with connection-local variables:

```elisp (connection-local-set-profile-variables 'urgrep-ripgrep '((urgrep-preferred-tools . (ripgrep))))

(connection-local-set-profiles '(:application tramp :machine "imagewriter") 'urgrep-ripgrep) ```

Using with wgrep

wgrep provides a convenient way to edit results in grep-like buffers. Urgrep can hook into wgrep to support this as well. To enable this, just load urgrep-wgrep.el.

Using with Xref

Xref lets you search through your projects to find strings, identifiers etc. You can make Xref use Urgrep to generate its search command by loading urgrep-xref.el.

Using with outline-minor-mode

Inside of Urgrep buffers, you can enable outline-minor-mode. This will let you toggle the visibility of each file's results.

Using with Eshell

In Eshell buffers, you can call urgrep much like you'd call any command-line recursive grep command. The following options are supported:

Option Action
-G, --basic-regexp Pattern is a basic regexp
-E, --extended-regexp Pattern is an extended regexp
-P, --perl-regexp Pattern is a Perl-compatible regexp
-R, --default-regexp Pattern is a regexp with the default syntax
-F, --fixed-strings Pattern is a string
-s, --case-sensitive Search case-sensitively
-i, --ignore-case Search case-insensitively
-S, --smart-case Ignore case if pattern is all lower-case
--group / --no-group Enable/disable grouping results by file
--hidden / --no-hidden Enable/disable searching hidden files
-Cn, --context=n Show n lines of context
-Bn, --before-context=n Show n lines of leading context
-An, --after-context=n Show n lines of trailing context

Programmatic interface

In addition to interactive use, Urgrep is designed to allow for programmatic use, returning a command to execute with the specified query and options: urgrep-command. This takes a query as well as several optional keyword arguments. For more information, consult the docstring for urgrep-command.


This project assigns copyright to the Free Software Foundation, so if you'd like to contribute code, please make sure you've filled out the assignment form and that it's up to date. In any case, before submitting patches, it's probably best to file an issue first so that we can discuss the best way to do things.

Old versions

urgrep-0.4.1.tar.lz2024-Mar-3119.5 KiB
urgrep-0.4.0.tar.lz2024-Jan-2219.4 KiB
urgrep-0.3.0.tar.lz2023-Dec-1718.8 KiB
urgrep-0.2.0.tar.lz2023-Sep-0117.7 KiB
urgrep-0.1.1.tar.lz2023-Jun-0716.3 KiB
urgrep-0.1.0.tar.lz2023-May-1316.2 KiB


Urgrep News

v0.5.0 (2024-05-11)

New features
  • Add ability to immediately adjust search options in the results buffer
Breaking changes
  • In the Urgrep minibuffer, toggling search of hidden files now uses M-s H

v0.4.1 (2024-03-10)

Bug fixes
  • Fix highlighting of matches when using Ugrep

v0.4.0 (2024-01-22)

New features
  • Add support for outline-minor-mode
Bug fixes
  • Fix invocation of ripgrep and ugrep on Windows

v0.3.0 (2023-12-17)

New features
  • Add optional urgrep-xref feature, which lets Xref use Urgrep to create the command for searching in files/directories
Bug fixes
  • Respect buffer-local values of urgrep-preferred-tools
Breaking changes
  • :files keyword argument in urgrep-command and friends is now :file-wildcard
  • :directory keyword argument in urgrep-commnd and friends is now :root, and can accept file and/or directory names

v0.2.0 (2023-08-31)

New features
  • Add support for toggling whether to search in hidden files (M-s h in the search prompt, or urgrep-search-hidden-files globally)
  • Add :directory key to urgrep-command, allowing you to specify zero or more directories to search in
  • urgrep builtin for Eshell now supports specifying search directories as arguments
  • Allow setting the search tool to use on the fly when reading the query (M-s t in the search prompt)
Breaking changes
  • urgrep-run-command now takes :tool as an optional key to match urgrep

v0.1.1 (2023-06-07)

Bug fixes
  • Fix Eshell integration

v0.1.0 (2023-05-13)

Initial release