AG(1)

✨ NAME ✨

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

🧚 SYNOPSIS 🧚

ag [options] pattern [path ...]

💖 DESCRIPTION 💖

okay so ag recursively searches for PATTERN in PATH 🔍 It's like grep or ack, but it's lowkey faster and it's giving speed ⚡

🎀 OPTIONS 🎀

• --ackmate — outputs results in a format AckMate can parse 🫶 check it out at https://github.com/protocool/AckMate
• --[no]affinity — sets thread affinity, but only if your platform supports it 🧵 Default is true.
• -a, --all-types — searches all files 💅 It doesn't include hidden files, and it doesn't respect any ignore files, so be careful bestie 💀
• -A, --after [LINES] — prints lines after each match ✨ If you don't give it a number, LINES defaults to 2.
• -B, --before [LINES] — prints lines before each match 🌸 If you don't give it a number, LINES defaults to 2.
• --[no]break — prints a newline between matches in different files 🍓 Enabled by default.
• -c, --count — only prints the number of matches in each file 🔢

Note: this counts matches, not matching lines. If you want the number of matching lines, pipe the output to wc -l 🙈

• --[no]color — prints color codes in results 🌈 Enabled by default.
• --color-line-number — sets the color codes for line numbers 💜 Default is 1;33.
• --color-match — sets the color codes for the match numbers in results 💜 Default is 30;43.
• --color-path — sets the color codes for path names 💚 Default is 1;32.
• --column — prints column numbers in results 📍
• -C, --context [LINES] — prints lines before and after matches 🫧 Default is 2.
• -D, --debug — outputs a ridiculous amount of debugging info 😭 Not useful unless you're actually debugging, bestie.
• --depth NUM — searches up to NUM directories deep, and -1 means unlimited 🪜 Default is 25.
• --[no]filename — prints file names 📁 Enabled by default, except when you're searching a single file.
• -f, --[no]follow — follows symlinks 🔗 Default is false.
• -F, --fixed-strings — an alias for --literal, so grep users feel at home 🏠
• --[no]group — the default, --group, lumps multiple matches in the same file together under one filename header 🎀 --nogroup skips that and puts the filename at the start of every match line instead.
• -g PATTERN — prints the filenames that match PATTERN 🗂️
• -G, --file-search-regex PATTERN — only searches files whose names match PATTERN 🎯
• -H, --[no]heading — prints filenames above the matching contents 👑
• --hidden — searches hidden files 🙈 This option still obeys ignored files.
• --ignore PATTERN — ignores files and directories whose names match this pattern 🚫 Literal file and directory names work too.
• --ignore-dir NAME — an alias for --ignore so ack users feel seen 🫶
• -i, --ignore-case — matches case-insensitively 🫠
• -l, --files-with-matches — only prints the names of files that have matches, not the matching lines 📝 An empty query will print every file that would be searched.
• -L, --files-without-matches — only prints the names of files that don't have matches 🙅‍♀️
• --list-file-types — shows the file types you can use, see FILE TYPES below 🦋
• -m, --max-count NUM — skips the rest of a file after NUM matches ✂️ Default is 0, which never skips.
• --[no]mmap — toggles memory-mapped I/O 🧠 Defaults to true on platforms where mmap() is faster than read(). (That's all of them except macOS 🍎)
• --[no]multiline — matches regexes across newlines 🧵 Enabled by default.
• -n, --norecurse — doesn't recurse into directories 🛑
• --[no]numbers — prints line numbers 🔢 By default, line numbers are omitted when searching streams.
• -o, --only-matching — prints only the matching part of each line 🎯
• --one-device — when recursing, skips directories that live on other storage devices 🌐 This is how you dodge slow network mounts 🐢 Not supported on every platform, sadly.
• -p, --path-to-ignore STRING — gives a path to a specific .ignore file 📂
• --pager COMMAND — uses a pager like less 📖 Use --nopager to override it. This option is also ignored if the output is piped to another program.
• --parallel — treats the input stream as a search term instead of data to search 🧚 This is meant for tools like GNU parallel. For example:

echo "foo\nbar\nbaz" | parallel "ag {} ."

This runs 3 instances of ag, searching the current directory for "foo", "bar", and "baz" ✨

• --print-long-lines — prints matches on super long lines 📏 (anything over 2k characters by default)
• --passthrough, --passthru — when searching a stream, prints all lines, even the ones that don't match 🌊
• -Q, --literal — doesn't parse PATTERN as a regular expression, just tries to match it literally 🧾
• -r, --recurse — recurses into directories when searching 🌳 Default is true.
• -s, --case-sensitive — matches case-sensitively 💎
• -S, --smart-case — matches case-sensitively if PATTERN has any uppercase letters, and case-insensitively otherwise 🧠 Enabled by default.
• --search-binary — searches binary files for matches 🤖
• --silent — suppresses all log messages, including errors 🤫
• --stats — prints stats like files scanned and time taken 📊
• --stats-only — prints those same stats and nothing else 📊
• -t, --all-text — searches all text files 📄 This doesn't include hidden files.
• -u, --unrestricted — searches all files 🔓 It ignores .ignore, .gitignore, etc., and searches binary and hidden files as well 💀
• -U, --skip-vcs-ignores — ignores VCS ignore files (.gitignore, .hgignore), but still uses .ignore 🫶
• -v, --invert-match — matches every line that does not contain the pattern 🙃
• -V, --version — prints version info 🏷️
• --vimgrep — outputs results in the same form as Vim's :vimgrep /pattern/g 🖊️ Here's a ~/.vimrc config example:

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

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

• -w, --word-regexp — only matches whole words 💬
• --workers NUM — uses NUM worker threads 🧵 Default is the number of CPU cores, with a max of 8.
• -z, --search-zip — searches the contents of compressed files 🗜️ Right now, gz and xz are supported. This option requires that ag is built with lzma and zlib.
• -0, --null, --print0 — separates the filenames with \0 instead of \n 🧩 This lets xargs -0 <command> correctly handle filenames with spaces or newlines 🫧

🦋 FILE TYPES 🦋

It's 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 ✨

🌸 IGNORING FILES 🌸

By default, ag ignores 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 too. 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 -t to search all text files, -a to search all files, and -u to search all of them, including hidden files 🔓

💅 EXAMPLES 💅

• ag printf — finds matches for "printf" in the current directory 🔍
• ag foo /bar/ — finds matches for "foo" in the path /bar/ 📂
• ag -- --foo — finds matches for "--foo" in the current directory 🧠 As with most UNIX command line utilities, -- tells ag that the remaining arguments shouldn't be treated as options, which is a whole mood 🫶

👑 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) 🍓

---

Bestie, that's the whole page, and it was last updated in December 2016 💜 Go be a AG(1) legend 👑✨