28.4 Searching with Grep under Emacs

Just as you can run a compiler from Emacs and then visit the lines with compilation errors, you can also run grep and then visit the lines on which matches were found. This works by treating the matches reported by grep as if they were errors. The output buffer uses Grep mode, which is a variant of Compilation mode (see Compilation Mode).

M-x grep
M-x lgrep

Run grep asynchronously under Emacs, listing matching lines in the buffer named *grep*.

M-x grep-find
M-x find-grep
M-x rgrep

Run grep via find, and collect output in the *grep* buffer.

M-x zrgrep

Run zgrep and collect output in the *grep* buffer.

M-x kill-grep

Kill the running grep subprocess.

To run grep, type M-x grep, then enter a command line that specifies how to run grep. Use the same arguments you would give grep when running it normally: a grep-style regexp (usually in single-quotes to quote the shell’s special characters) followed by file names, which may use wildcards. If you specify a prefix argument for M-x grep, it finds the identifier (see Find Identifier References) in the buffer around point, and puts that into the default grep command.

Your command need not simply run grep; you can use any shell command that produces output in the same format. For instance, you can chain grep commands, like this:

grep -nH -e foo *.el | grep bar | grep toto

The output from grep goes in the *grep* buffer. You can find the corresponding lines in the original files using M-g M-n, RET, and so forth, just like compilation errors. See Compilation Mode, for detailed description of commands and key bindings available in the *grep* buffer.

Some grep programs accept a ‘--color’ option to output special markers around matches for the purpose of highlighting. You can make use of this feature by setting grep-highlight-matches to t. When displaying a match in the source buffer, the exact match will be highlighted, instead of the entire source line. Highlighting is provided via matching the ANSI escape sequences emitted by grep. The matching of the sequences is controlled by grep-match-regexp, which can be customized to accommodate different grep programs.

As with compilation commands (see Running Compilations under Emacs), while the grep command runs, the mode line shows the running number of matches found and highlighted so far.

The grep commands will offer to save buffers before running. This is controlled by the grep-save-buffers variable. The possible values are either nil (don’t save), ask (ask before saving), or a function which will be used as a predicate (and is called with the file name as the parameter and should return non-nil if the buffer is to be saved). Any other non-nil value means that all buffers should be saved without asking. The default is ask.

The command M-x grep-find (also available as M-x find-grep) is similar to M-x grep, but it supplies a different initial default for the command—one that runs both find and grep, so as to search every file in a directory tree. See also the find-grep-dired command, in Dired and find.

The commands M-x lgrep (local grep) and M-x rgrep (recursive grep) are more user-friendly versions of grep and grep-find, which prompt separately for the regular expression to match, the files to search, and the base directory for the search. Case sensitivity of the search is controlled by the current value of case-fold-search. The command M-x zrgrep is similar to M-x rgrep, but it calls zgrep instead of grep to search the contents of gzipped files.

These commands build the shell commands based on the variables grep-template (for lgrep) and grep-find-template (for rgrep). The files to search can use aliases defined in the variable grep-files-aliases.

Directories listed in the variable grep-find-ignored-directories are automatically skipped by M-x rgrep. The default value includes the data directories used by various version control systems.

By default, the shell commands constructed for lgrep, rgrep, and zgrep are abbreviated for display by concealing the part that contains a long list of files and directories to ignore. You can reveal the concealed part by clicking on the button with ellipsis, which represents them. You can also interactively toggle viewing the concealed part by typing M-x grep-find-toggle-abbreviation. To disable this abbreviation of the shell commands, customize the option grep-find-abbreviate to a nil value.