.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "AG" "1" "May 2020" "" ""
.
.SH "NAME"
\fBag\fR \- The Silver Searcher\. Like ack, but faster\.
.
.SH "SYNOPSIS"
\fBag\fR [\fIoptions\fR] \fIpattern\fR [\fIpath \.\.\.\fR]
.
.SH "DESCRIPTION"
Recursively search for PATTERN in PATH\. Like grep or ack, but faster\.
.
.SH "OPTIONS"
.
.TP
\fB\-\-ackmate\fR
Output results in a format parseable by AckMate \fIhttps://github\.com/protocool/AckMate\fR\.
.
.TP
\fB\-\-[no]affinity\fR
Set thread affinity (if platform supports it)\. Default is true\.
.
.TP
\fB\-\-agrc\fR=\fIFILE\fR
Use \fIFILE\fR instead of $AGRC or $HOME/\.agrc for default options\. Specify \fB\-\-no\-agrc\fR to disable reading from an agrc file\. See \fIAGRC\fR for details\.
.
.TP
\fB\-a \-\-all\-types\fR
Search all files\. This doesn\'t include hidden files, and doesn\'t respect any ignore files\.
.
.TP
\fB\-A \-\-after\fR[=\fILINES\fR]
Print lines after match\. If not provided, \fILINES\fR defaults to 2\.
.
.TP
\fB\-B \-\-before\fR[=\fILINES\fR]
Print lines before match\. If not provided, \fILINES\fR defaults to 2\.
.
.TP
\fB\-\-[no]break\fR
Print a newline between matches in different files\. Enabled by default\.
.
.TP
\fB\-c \-\-count\fR
Only print the number of matches in each file\. Note: This is the number of matches, \fBnot\fR the number of matching lines\. Pipe output to \fBwc \-l\fR if you want the number of matching lines\.
.
.TP
\fB\-\-[no]color\fR
Print color codes in results\. Enabled by default\.
.
.TP
\fB\-\-color\-line\-number\fR
Color codes for line numbers\. Default is 1;33\.
.
.TP
\fB\-\-color\-match\fR
Color codes for result match numbers\. Default is 30;43\.
.
.TP
\fB\-\-color\-path\fR
Color codes for path names\. Default is 1;32\.
.
.TP
\fB\-\-column\fR
Print column numbers in results\.
.
.TP
\fB\-C \-\-context\fR[=\fILINES\fR]
Print lines before and after matches\. If not provided, \fILINES\fR defaults to 2\.
.
.TP
\fB\-D \-\-debug\fR
Output ridiculous amounts of debugging info\. Not useful unless you\'re actually debugging\.
.
.TP
\fB\-\-depth\fR=\fINUM\fR
Search up to \fINUM\fR directories deep, \-1 for unlimited\. Default is 25\.
.
.TP
\fB\-E \-\-extension\fR=\fIEXT\fR
Search files with this extension\. Equivalent to \fB\-j \-G \'\e\.EXT$\'\fR (\fIEXT\fR could be a regex fragment)\.
.
.TP
\fB\-\-[no]filename\fR
Print file names\. Enabled by default, except when searching a single file\.
.
.TP
\fB\-f \-\-[no]follow\fR
Follow symlinks\. Default is false\.
.
.TP
\fB\-F \-\-fixed\-strings\fR
Alias for \-\-literal for compatibility with grep\.
.
.TP
\fB\-\-[no]group\fR
The default, \fB\-\-group\fR, lumps multiple matches in the same file together, and presents them under a single occurrence of the filename\. \fB\-\-nogroup\fR refrains from this, and instead places the filename at the start of each match line\.
.
.TP
\fB\-g \-\-filename\-pattern\fR=\fIPATTERN\fR
Print filenames matching \fIPATTERN\fR\.
.
.TP
\fB\-G \-\-file\-search\-regex\fR=\fIPATTERN\fR
Only search files whose names match \fIPATTERN\fR\.
.
.TP
\fB\-H \-\-[no]heading\fR
Print filenames above matching contents\.
.
.TP
\fB\-\-help\-types\fR
Alias for \-\-list\-file\-types for compatibility with ack\.
.
.TP
\fB\-\-hidden\fR
Search hidden files\. This option obeys ignored files\.
.
.TP
\fB\-I \-\-ignore\fR=\fIPATTERN\fR
Ignore files/directories whose names match \fIPATTERN\fR\. Literal file and directory names are also allowed\.
.
.TP
\fB\-\-ignore\-dir\fR=\fIPATTERN\fR
Alias for \-\-ignore for compatibility with ack\.
.
.TP
\fB\-i \-\-ignore\-case\fR
Match case\-insensitively\.
.
.TP
\fB\-j \-\-just\-filename\fR
Search only the file name, not the full path, when using a file search regex (such as with \-g or \-G)\.
.
.TP
\fB\-l \-\-files\-with\-matches\fR
Only print the names of files containing matches, not the matching lines\. An empty query will print all files that would be searched\.
.
.TP
\fB\-L \-\-files\-without\-matches\fR
Only print the names of files that don\'t contain matches\.
.
.TP
\fB\-\-list\-file\-types\fR
See \fBFILE TYPES\fR below\.
.
.TP
\fB\-m \-\-max\-count\fR=\fINUM\fR
Skip the rest of a file after \fINUM\fR matches\. Default is 0, which never skips\.
.
.TP
\fB\-\-[no]mmap\fR
Toggle use of memory\-mapped I/O\. Defaults to true on platforms where \fBmmap()\fR is faster than \fBread()\fR\. (All but macOS\.)
.
.TP
\fB\-\-[no]multiline\fR
Match regexes across newlines\. Enabled by default\.
.
.TP
\fB\-n \-\-norecurse\fR
Don\'t recurse into directories\.
.
.TP
\fB\-\-[no]numbers\fR
Print line numbers\. Default is to omit line numbers when searching streams or a single file\.
.
.TP
\fB\-o \-\-only\-matching\fR
Print only the matching part of the lines\.
.
.TP
\fB\-\-one\-device\fR
When recursing directories, don\'t scan dirs that reside on other storage devices\. This lets you avoid scanning slow network mounts\. This feature is not supported on all platforms\.
.
.TP
\fB\-p \-\-path\-to\-ignore\fR=\fIPATH\fR
Provide \fIPATH\fR pointing to a specific \.ignore file\.
.
.TP
\fB\-P \-\-pager\fR=\fICOMMAND\fR
Use a pager such as \fBless\fR\. Use \fB\-\-nopager\fR to override\. This option is also ignored if output is piped to another program\. The pager selected is selected from (in order): the command line argument, the PAGER environment variable, the command "less"
.
.TP
\fB\-\-parallel\fR
Parse the input stream as a search term, not data to search\. This is meant to be used with tools such as GNU parallel\. For example: \fBecho "foo\enbar\enbaz" | parallel "ag {} \."\fR will run 3 instances of ag, searching the current directory for "foo", "bar", and "baz"\.
.
.TP
\fB\-\-print\-long\-lines\fR
Print matches on very long lines (> 2k characters by default)\.
.
.TP
\fB\-\-passthrough \-\-passthru\fR
When searching a stream, print all lines even if they don\'t match\.
.
.TP
\fB\-Q \-\-literal\fR
Do not parse \fIPATTERN\fR as a regular expression\. Try to match it literally\.
.
.TP
\fB\-q \-\-silent\fR
Suppress all log messages, including errors\.
.
.TP
\fB\-r \-\-recurse\fR
Recurse into directories when searching\. Default is true\.
.
.TP
\fB\-s \-\-case\-sensitive\fR
Match case\-sensitively\.
.
.TP
\fB\-S \-\-smart\-case\fR
Match case\-sensitively if there are any uppercase letters in \fIPATTERN\fR, case\-insensitively otherwise\. Enabled by default\.
.
.TP
\fB\-\-search\-binary\fR
Search binary files for matches\.
.
.TP
\fB\-\-stats\fR
Print stats (files scanned, time taken, etc)\.
.
.TP
\fB\-\-stats\-only\fR
Print stats (files scanned, time taken, etc) and nothing else\.
.
.TP
\fB\-t \-\-all\-text\fR
Search all text files\. This doesn\'t include hidden files\.
.
.TP
\fB\-u \-\-unrestricted\fR
Search \fIall\fR files\. This ignores \.ignore, \.gitignore, etc\. It searches binary and hidden files as well\.
.
.TP
\fB\-U \-\-skip\-vcs\-ignores\fR
Ignore VCS ignore files (\.gitignore, \.hgignore), but still use \.ignore\.
.
.TP
\fB\-v \-\-invert\-match\fR
Match every line \fInot\fR containing the specified pattern\.
.
.TP
\fB\-V \-\-version\fR
Print version info\.
.
.TP
\fB\-\-vimgrep\fR
Output results in the same form as Vim\'s \fB:vimgrep /pattern/g\fR
.
.IP
Here is a ~/\.vimrc configuration example:
.
.IP
\fBset grepprg=ag\e \-\-vimgrep\e $*\fR \fBset grepformat=%f:%l:%c:%m\fR
.
.IP
Then use \fB:grep\fR to grep for something\. Then use \fB:copen\fR, \fB:cn\fR, \fB:cp\fR, etc\. to navigate through the matches\.
.
.TP
\fB\-w \-\-word\-regexp\fR
Only match whole words\.
.
.TP
\fB\-\-workers\fR=\fINUM\fR
Use \fINUM\fR worker threads\. Default is the number of CPU cores, with a max of 8\.
.
.TP
\fB\-W \-\-width\fR=\fINUM\fR
Truncate match lines after \fINUM\fR characters\.
.
.TP
\fB\-X \-\-invert\-file\-search\-regex\fR=\fIPATTERN\fR
Like \-G, but only search files whose names do not match \fIPATTERN\fR\. File\-type searches are still used and not inverted\.
.
.TP
\fB\-z \-\-search\-zip\fR
Search contents of compressed files\. Currently, gz and xz are supported\. This option requires that ag is built with lzma and zlib\.
.
.TP
\fB\-Z \-\-null\-lines\fR
Use NULL (\fB\e0\fR) as the newline separator instead of \fB\en\fR\. This is primarily useful for searching special files such as /proc/pid/environ\. It applies globally to all files searched, and \fB\en\fR is NOT treated as a newline\. This means that if a normal text file (that contains no null bytes) contains a match, the entire file will be printed as though it were a single line\. This setting does not affect how newlines in regex patterns are handled (i\.e\. it doesn\'t change PCRE matching)\.
.
.TP
\fB\-0 \-\-null \-\-print0\fR
Separate the filenames with \fB\e0\fR, rather than \fB\en\fR: this allows \fBxargs \-0 <command>\fR to correctly process filenames containing spaces or newlines\.
.
.SH "FILE TYPES"
It is possible to restrict the types of files searched\. For example, passing \fB\-\-html\fR will search only files with the extensions \fBhtm\fR, \fBhtml\fR, \fBshtml\fR or \fBxhtml\fR\. For a list of supported types, run \fBag \-\-list\-file\-types\fR\.
.
.SH "IGNORING FILES"
By default, ag will ignore files whose names match patterns in \.gitignore, \.hgignore, or \.ignore\. These files can be anywhere in the directories being searched\. Binary files are ignored by default as well\. Finally, ag looks in $HOME/\.agignore for ignore patterns\.
.
.P
If you want to ignore \.gitignore and \.hgignore, but still take \.ignore into account, use \fB\-U\fR\.
.
.P
Use the \fB\-t\fR option to search all text files; \fB\-a\fR to search all files; and \fB\-u\fR to search all, including hidden files\.
.
.SH "AGRC"
To modify the "default" options, ag can read a list of command\-line arguments from an "agrc" file\. One "agrc" file will be selected as the first of 1) the \fIPATH\fR in \fB\-\-agrc\fR=\fIPATH\fR, 2) the environment variable \fBAGRC\fR, or 3) the default \fB$HOME/\.agrc\fR\.
.
.P
If \fB\-\-noagrc\fR is specified, an "agrc" file will not be used\.
.
.P
The "agrc" file should contain a list of command\-line arguments, one per line\. You don\'t need to quote arguments as you would in a shell as the entire line will be considered a single argument\. For long options which take a value, use the form \fB\-\-option=value\fR rather than \fB\-\-option value\fR\.
.
.SH "EXAMPLES"
\fBag printf\fR: Find matches for "printf" in the current directory\.
.
.P
\fBag foo /bar/\fR: Find matches for "foo" in path /bar/\.
.
.P
\fBag \-\- \-\-foo\fR: Find matches for "\-\-foo" in the current directory\. (As with most UNIX command line utilities, "\-\-" is used to signify that the remaining arguments should not be treated as options\.)
.
.SH "ABOUT"
ag was originally created by Geoff Greer\. More information (and the latest release) can be found at http://geoff\.greer\.fm/ag
.
.P
This man page is part of Allen Wild\'s fork of ag, which uses version 2 of the PCRE library and other additional features: https://github\.com/aswild/the_silver_searcher
.
.SH "SEE ALSO"
grep(1)