Formatting Flags

Only Filenames (-l)

Returns only file names with at least one match. Stops reading each file after the first match — very efficient for large directories.

# Which files contain "FIXME"?
ag -l "FIXME"

# Pipe to sed for bulk replacement
ag -l "old_function" src/ | xargs sed -i 's/old_function/new_function/g'

Count Matches Per File (-c)

ag -c "TODO" src/
# src/app.py:3
# src/utils.py:1
# src/models.py:7

Print Only the Match (-o)

Discard the surrounding line; print only the exact matched text (one per line):

# Extract all email addresses
ag -o "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}" contacts.txt

# Extract all version numbers
ag -o "v[0-9]+\.[0-9]+\.[0-9]+" CHANGELOG.md

Column Numbers (--column)

Show the column number of each match — useful for editor integration:

ag --column "TODO" src/
# src/app.py:42:5: TODO: refactor this

Remove Heading (--noheading)

By default ag groups results under a filename header. --noheading produces traditional file:line:col:text format:

ag --noheading "pattern" . | awk -F: '{print $1}' | sort -u

Quiet (-q)

Suppress all output. Only returns the exit code — ideal for conditional scripting:

if ag -q "CRITICAL" /var/log/app.log; then
    send_alert.sh "Critical errors found"
fi