The Silver Searcher (ag)

A comprehensive guide to mastering ag — the original fast, developer-friendly code search tool that inspired ripgrep. Written in C, ag searches source code with .gitignore awareness, PCRE regex, and colorized output.

Mental model: ag is grep -rn with .gitignore automatically applied, colors enabled, and a faster search engine. It was the first mainstream tool to treat version control as a first-class citizen in search.

Where ag Sits in the Ecosystem

Tool	Speed	.gitignore	Regex Engine	Notable
grep	Fast	No	POSIX/PCRE	Universal, portable
ag	Very fast	Yes	PCRE	C-based, wide install base
rg	Blazing	Yes	Rust/PCRE2	Newest, fastest

ag predates rg by several years and remains widely installed on servers and developer machines where rg is not yet available.

Curriculum

1. Introduction

• What is ag? — History, architecture, and when to choose ag.
• Installing ag — apt, brew, and manual builds.

2. Core Syntax

• Basic Search — Pattern, path, and output format.
• Multiple Patterns — OR logic and chaining.

3. Smart Defaults

• Gitignore Awareness — What ag ignores automatically.
• The .agignore File — Custom exclusion rules.

4. Regex & Patterns

• PCRE Regex — Full PCRE support including lookaheads.
• Fixed Strings — -Q for literal searches.

5. File & Type Filtering

• File Type Filters — --python, --js, and custom types.
• Depth and Glob — --depth, -G for path patterns.

6. Output & Context

• Context Lines — -A, -B, -C.
• Formatting Flags — -l, -c, -o, --noheading.

7. Performance

• Speed Tuning — Mmap, worker threads, and skip strategies.

8. Real World Workflows

• Code Search Workflows — Finding functions, TODOs, and deprecated APIs.
• Editor Integration — Vim, Emacs, and shell functions.

9. Troubleshooting

• Common Issues — Missing results, binary files, encoding.

10. Cheatsheet

• ag Cheatsheet — All flags and quick pipelines.

---

Quick Start

# Install
sudo apt install silversearcher-ag   # Ubuntu/Debian

# Basic search
ag "TODO"                     # search cwd, respects .gitignore
ag -t py "def process"        # Python files only
ag -l "api_key" /etc          # just filenames
ag -C 3 "Exception" logs/     # 3 lines of context