name: ag description: > High-speed repository and document text search with The Silver Searcher (ag). Use when the user asks for ag/Silver Searcher explicitly, or when tasks need fast recursive matching, filename filtering, match counting, ignore-aware scanning (.gitignore/.hgignore/.ignore/$HOME/.agignore), context extraction, script-friendly result lists, multi-file search, file type filtering, or performance-critical searching.

Ag Search

Use ag to find text across code and documents quickly with the right scope, output mode, and ignore behavior.

Prerequisite Check

Run this before proposing ag-based search:

command -v ag >/dev/null 2>&1 || ag --version

If ag is missing, surface that first and either run scripts/install.sh or scripts/install.ps1, or fall back to rg and then grep -R when the user still needs search results in the current runtime.

Quick Start

1. Confirm the binary exists: ag --version
2. Start with a bounded search: ag --numbers --column 'pattern' .
3. Narrow output before scaling up: ag -l 'pattern' . or ag -c 'pattern' .
4. If ag is unavailable, continue with rg 'pattern' . or grep -R --line-number 'pattern' .

Intent Router

Workflow

1. Confirm search goal: matching lines, matching files, counts, filename search, or inverse match.
2. Pick pattern mode:

• Regex (default)
• Literal: -Q / --literal
• Whole word: -w
• If pattern starts with a dash, use -- before the pattern.

1. Pick scope:

• Path(s): ag '<pattern>' <path>
• File name restriction: -G '<file-regex>'
• File type restriction: run ag --list-file-types, then use --<type>
• Depth restriction: --depth <num>

1. Pick output:

• Files only: -l
• Count per file: -c
• Column and line numbers: --column --numbers
• Script-safe filenames: -0 with xargs -0

1. Run and summarize totals plus notable matches.

Ignore and Visibility Rules

Default behavior:

• Obey .gitignore, .hgignore, .ignore, and $HOME/.agignore
• Skip binary files

Overrides:

• --hidden: include hidden files and still obey ignore files
• -U: ignore VCS ignore files and still obey .ignore
• -t: search all text files (not hidden)
• -a: search all file types (not hidden)
• -u: unrestricted (hidden + binary + ignore bypass)

Command Patterns

• Basic recursive search: ag '<pattern>' .
• Literal string search: ag -Q '<literal>' .
• Files containing match: ag -l '<pattern>' .
• Count matches per file: ag -c '<pattern>' .
• Filename-only search: ag -g '<filename-regex>' .
• Search pattern only in matching filenames: ag -G '<filename-regex>' '<pattern>' .
• Include context lines: ag -C 2 '<pattern>' .
• Search compressed content (if supported): ag -z '<pattern>' .
• Safe pipeline:

ag -l -0 '<pattern>' . | xargs -0 <command>

# Preferred fallback order when ag is unavailable
rg --line-number '<pattern>' .
grep -R --line-number -- '<pattern>' .

Safety and Guardrails

Practical Guardrails

• Quote patterns to avoid shell expansion.
• For machine-readable output, add --nocolor and optionally --nogroup.
• For very large trees, start with -l, -c, or --depth to control output volume.
• Runtime defaults can vary by build/version; check ag --help on this machine when behavior differs.
• Run probe script first: scripts/probe-ag.sh to verify ag availability and features
• Recovery note: when falling back from ag, call out behavior differences. rg and grep -R do not match ag's ignore rules and file-type flags exactly.

Sources

• Official repository: https://github.com/ggreer/the_silver_searcher
• README: https://raw.githubusercontent.com/ggreer/the_silver_searcher/master/README.md
• Manpage source: https://raw.githubusercontent.com/ggreer/the_silver_searcher/master/doc/ag.1.md