ag 命令的帮助文档

安装

the silver searcher 在各大平台上都可以从软件库直接安装。除了 Debian/Ubuntu 外，其他系统使用的包名都是一样的。

MacOS:

brew install the_silver_searcher

Debian/Ubuntu:

sudo apt-get install silversearcher-ag

CentOS:

sudo yum install the_silver_searcher

Fedora:

sudo dnf install the_silver_searcher

ArchLinux:

sudo pacman -S the_silver_searcher

安装后，系统会新增一个 ag 指令来使用 the silver searcher。作者应该是看穿了人类懒惰的本性，选取了一个比 grep 更短的名字。

常用命令

使用语法：

ag [options] pattern [path ...]
ag [可选项] 匹配模式 [路径...]

由于模式可以是一个正则表达式，使得搜索功能极为强大。

下面介绍一些常用的场景：

ag -A 3 "string-to-search"

此时 ag 会遍历当前目录下的文本文件，在每个文件的每一行中查找 "string-to-search" 这种模式，把文件名、行号和匹配的内容高亮显示出来，同时显示了匹配行数的后3行。-C/--context [LINES] ，输出匹配内容前后[ LINES ]行内容（默认2行）

如果想在某个指定的目录下搜索，或只搜索某个文件的内容，在搜索的字符串后面加上路径就行：

ag "string-to-search" /path/to/directory

除此以外，ag -G 提供了强大的过滤功能，使搜索在特定的文件中进行。下面的例子只搜索 java 类型的文件：

ag -G ".+\.java" "string-to-search" /path/to/directory

ag 根据输入智能判定大小写的匹配方式。如果查询的字符串只含有小写字符，使用大小写不敏感的匹配方式；如果出现了大写字符，就改为大小写敏感的匹配方式。如果想要直接使用不敏感的匹配方式，请用 ag -i 选项。

另一个很有用的选项是 ag -w 的全词匹配，它要求匹配的字符串前后都需要有合适的分隔符。

如果想要搜索不满足特定模式的行，用 ag -v 对搜索结果取反。

最后，如果只关心有哪些文件匹配（而不在意文件的内容），可以用 ag -l 显示有匹配的文件名，类似的 ag -L 显示没有任何匹配的文件名。

参考：

• the silver searcher：快如闪电的 grep

帮助文档

NAME
       ag - The Silver Searcher. Like ack, but faster.

SYNOPSIS
       ag [options] pattern [path ...]
		  ag [可选项] 匹配模式 [路径...]
DESCRIPTION
       Recursively search for PATTERN in PATH. Like grep or ack, but faster.
		  递归搜索路径中的模式。像grep或ack，但更快
OPTIONS
       --ackmate
              Output results in a format parseable by AckMate https://github.com/protocool/AckMate.
					输出结果以AckMate可解析的格式输出
       --[no]affinity
              Set thread affinity (if platform supports it). Default is true.
			  设置线程关联(如果平台支持的话)。默认是True
       -a --all-types
              Search all files. This doesn´t include hidden files, and doesn´t respect any ignore files.
			  搜索所有文件。这不包括隐藏文件,也不包括任何ignore文件。
       -A --after [LINES]
              Print lines after match. If not provided, LINES defaults to 2.
			  打印匹配项之后的行数。如果不提供行数，使用这个参数的话，就默认显示匹配项之后的2行
       -B --before [LINES]
              Print lines before match. If not provided, LINES defaults to 2.
			  打印匹配项之前的行数。如果不提供行数，使用这个参数的话，就默认显示匹配项之前的2行
       --[no]break
              Print a newline between matches in different files. Enabled by default.
					在不同文件中的匹配项之间打印换行符。 默认情况下启用。使用--nobreak就不会换行了
       -c --count
              Only print the number of matches in each file. Note: This is the number of matches, not the number of matching lines. Pipe out‐
              put to wc -l if you want the number of matching lines.
					仅打印每个文件中的匹配数。 注意：这是匹配数，而不是匹配行数。如果你想要知道匹配的行数，使用管道命令，加上wc -l。★★★
       --[no]color
              Print color codes in results. Enabled by default.
					在结果中打印颜色。默认启用。
       --color-line-number
              Color codes for line numbers. Default is 1;33.
					行号的颜色，默认是1;33
       --color-match
              Color codes for result match numbers. Default is 30;43.
					结果中匹配数字的颜色。
       --color-path
              Color codes for path names. Default is 1;32.
					结果中路径的显示颜色
       --column
              Print column numbers in results.
					结果中列号的颜色
       -C --context [LINES]
              Print lines before and after matches. Default is 2.
					打印匹配项上下文的行数。默认显示2行。★★★
       -D --debug
              Output ridiculous amounts of debugging info. Not useful unless you´re actually debugging.
					输出大量的调试信息。 除非你实际调试，否则没用。
       --depth NUM
              Search up to NUM directories deep, -1 for unlimited. Default is 25.
					最多可搜索NUM个目录深度，-1表示无限制。 默认值为25。★★★
       --[no]filename
              Print file names. Enabled by default, except when searching a single file.
					打印文件名。 默认情况下启用，但搜索单个文件时除外
       -f --[no]follow
              Follow symlinks. Default is false.
					包含符号链接。默认是False.
       -F --fixed-strings
              Alias for --literal for compatibility with grep.
					别名为--literal，与grep兼容。
       --[no]group
              The default, --group, lumps multiple matches in the same file together, and presents them under  a  single  occurrence  of  the
              filename. --nogroup refrains from this, and instead places the filename at the start of each match line.
					默认--group，将同一个文件中的多个匹配项集中在一起，并在文件名下一行显示匹配结果。 --nogroup避免这种情况，而是将文件名放在每个匹配行的开头
       -g PATTERN
              Print filenames matching PATTERN.
			  打印与PATTERN匹配的文件名。★★★
       -G --file-search-regex PATTERN
              Only search files whose names match PATTERN.
			  仅搜索与PATTERN匹配的文件中的内容，后面还需要加上需要搜索的内容。★★
       -H --[no]heading
              Print filenames above matching contents.
			  打印匹配内容以上的文件名。
       --hidden
              Search hidden files. This option obeys ignored files.
					搜索隐藏文件。 此选项服从ignored文件。
       --ignore PATTERN
              Ignore files/directories whose names match this pattern. Literal file and directory names are also allowed.

       --ignore-dir NAME
              Alias for --ignore for compatibility with ack.

       -i --ignore-case
              Match case-insensitively.

       -l --files-with-matches
              Only  print  the  names  of files containing matches, not the matching lines. An empty query will print all files that would be
              searched.

       -L --files-without-matches
              Only print the names of files that don´t contain matches.

       --list-file-types
              See FILE TYPES below.

       -m --max-count NUM
              Skip the rest of a file after NUM matches. Default is 0, which never skips.

       --[no]mmap
              Toggle use of memory-mapped I/O. Defaults to true on platforms where mmap() is faster than read(). (All but macOS.)

       --[no]multiline
              Match regexes across newlines. Enabled by default.

       -n --norecurse
              Don´t recurse into directories.

       --[no]numbers
              Print line numbers. Default is to omit line numbers when searching streams.

       -o --only-matching
              Print only the matching part of the lines.

       --one-device
              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.

       -p --path-to-ignore STRING
              Provide a path to a specific .ignore file.

       --pager COMMAND
              Use a pager such as less. Use --nopager to override. This option is also ignored if output is piped to another program.

       --parallel
              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: echo "foo\nbar\nbaz" | parallel "ag {} ." will run 3 instances of ag,  searching  the  current  directory  for  "foo",
              "bar", and "baz".

       --print-long-lines
              Print matches on very long lines (> 2k characters by default).

       --passthrough --passthru
              When searching a stream, print all lines even if they don´t match.

       -Q --literal
              Do not parse PATTERN as a regular expression. Try to match it literally.

       -r --recurse
              Recurse into directories when searching. Default is true.

       -s --case-sensitive
              Match case-sensitively.

       -S --smart-case
              Match case-sensitively if there are any uppercase letters in PATTERN, case-insensitively otherwise. Enabled by default.

       --search-binary
              Search binary files for matches.

       --silent
              Suppress all log messages, including errors.

       --stats
              Print stats (files scanned, time taken, etc).

       --stats-only
              Print stats (files scanned, time taken, etc) and nothing else.

       -t --all-text
              Search all text files. This doesn´t include hidden files.

       -u --unrestricted
              Search all files. This ignores .ignore, .gitignore, etc. It searches binary and hidden files as well.

       -U --skip-vcs-ignores
              Ignore VCS ignore files (.gitignore, .hgignore), but still use .ignore.

       -v --invert-match
              Match every line not containing the specified pattern.

       -V --version
              Print version info.

       --vimgrep
              Output results in the same form as Vim´s :vimgrep /pattern/g

              Here is a ~/.vimrc configuration example:

              set grepprg=ag\ --vimgrep\ $* set grepformat=%f:%l:%c:%m

              Then use :grep to grep for something. Then use :copen, :cn, :cp, etc. to navigate through the matches.

       -w --word-regexp
              Only match whole words.

       --workers NUM
              Use NUM worker threads. Default is the number of CPU cores, with a max of 8.

       -z --search-zip
              Search  contents  of  compressed files. Currently, gz and xz are supported. This option requires that ag is built with lzma and
              zlib.

       -0 --null --print0
              Separate the filenames with \0, rather than \n: this allows xargs -0 <command> to correctly process filenames containing spaces
              or newlines.

FILE TYPES
       It  is  possible  to restrict the types of files searched. For example, passing --html will search only files with the extensions htm,
       html, shtml or xhtml. For a list of supported types, run ag --list-file-types.
		  ag --py xiang
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.

       If you want to ignore .gitignore and .hgignore, but still take .ignore into account, use -U.

       Use the -t option to search all text files; -a to search all files; and -u to search all, including hidden files.

EXAMPLES
       ag printf: Find matches for "printf" in the current directory.

       ag foo /bar/: Find matches for "foo" in path /bar/.

       ag  --  --foo:  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.)

ABOUT
       ag was originally created by Geoff Greer. More information (and the latest release) can be found at http://geoff.greer.fm/ag

SEE ALSO
       grep(1)

                                                                December 2016                                                           AG(1)