Binary Flags Reference¶

Ripgrep provides several flags to control how binary files are handled during search operations. These flags determine whether binary files are skipped, searched with warnings, or treated as plain text.

Binary Detection Modes¶

Ripgrep uses three binary handling modes (defined in crates/core/flags/lowargs.rs:233):

stateDiagram-v2
    [*] --> Auto: Default
    Auto --> SearchAndSuppress: "--binary flag
or explicit file"
    Auto --> AsText: --text/-a flag
    SearchAndSuppress --> Auto: --no-binary flag
    AsText --> Auto: --no-text flag
    SearchAndSuppress --> AsText: --text/-a flag
    AsText --> SearchAndSuppress: --binary flag

    note right of Auto
        Default behavior
        Explicit: warn
        Implicit: skip
    end note

    note right of SearchAndSuppress
        Always search
        Show warnings
    end note

    note right of AsText
        No binary detection
        Terminal corruption risk
    end note

Figure: Binary mode state transitions showing how flags switch between modes.

--binary¶

Purpose: Search binary files and show warnings instead of skipping them.

Effect: Applies SearchAndSuppress mode to implicit files, making them behave like explicit files.

Example:

# Show warnings for binary files in recursive search
rg --binary TODO  # (1)!

1. Applies SearchAndSuppress mode to implicit files (from recursive search)

--text / -a¶

Purpose: Completely disable binary detection, treating all files as text.

Effect: Sets AsText mode—no NUL byte detection, no special handling.

Example:

# Treat everything as text, even binaries
rg --text "pattern" binary_file.bin  # (1)!

1. Disables all binary detection - searches everything as plain text

--no-binary¶

Purpose: Disable the --binary flag.

Effect: Reverts to default Auto mode behavior.

Example:

# Explicitly disable binary warnings
rg --no-binary "pattern"

--no-text¶

Purpose: Disable the --text flag.

Effect: Re-enables binary detection if --text was set.

Example:

# Re-enable binary detection
rg --no-text "pattern"

Common Use Cases¶

Here are practical scenarios showing when to use each flag:

# Find TODO comments in source code, including compiled binaries
rg --binary "TODO"

src/main.rs:42:    // TODO: refactor this
Binary file libfoo.so matches (found "\0" byte around offset 123)
Binary file app.exe matches (found "\0" byte around offset 456)

# Search PostgreSQL dump that may contain NUL bytes
rg --text "user@example.com" database.dump

# Search logs that occasionally contain binary data
rg --binary "ERROR" /var/log/

/var/log/app.log:1234:ERROR: Connection failed
Binary file /var/log/metrics.bin matches (found "\0" byte around offset 789)

# Search binary files with output redirection
rg --text "pattern" *.bin > results.txt 2>&1

rg --binary "pattern" *.bin

# These behave identically - explicit files use SearchAndSuppress
rg "pattern" binary_file.bin
rg --binary "pattern" binary_file.bin

Binary file binary_file.bin matches

Decision Flowchart¶

Here's how ripgrep decides what to do with binary data:

flowchart TD
    Start[File to search] --> TextFlag{--text flag set?}

    TextFlag -->|Yes| AsText["Treat as text
AsText mode
No detection"]
    TextFlag -->|No| BinaryDetect[Binary detection enabled]

    BinaryDetect --> FileType{File explicit or implicit?}

    FileType -->|Explicit| Suppress1["Search and Suppress
Show warning"]
    FileType -->|Implicit| BinaryFlag{--binary flag set?}

    BinaryFlag -->|Yes| Suppress2["Search and Suppress
Show warning"]
    BinaryFlag -->|No| Skip["Quit early
Silent skip"]

    style AsText fill:#e1f5ff
    style Suppress1 fill:#fff3e0
    style Suppress2 fill:#fff3e0
    style Skip fill:#ffebee
    style TextFlag fill:#f3e5f5
    style FileType fill:#f3e5f5
    style BinaryFlag fill:#f3e5f5

Figure: Binary file handling decision tree showing how flags and file type affect behavior.

Implementation Details¶

The binary handling logic is implemented across several key components:

• BinaryMode enum (crates/core/flags/lowargs.rs:233-252): Defines the three modes (Auto, SearchAndSuppress, AsText). The SearchAndSuppress mode includes a comment explaining the memory usage optimization: NUL bytes are replaced with line terminators to prevent impractically large lines when treating binary data as line-oriented.
• BinaryDetection struct (crates/searcher/src/searcher/mod.rs:55): A wrapper around line_buffer::BinaryDetection that implements the NUL byte detection mechanism. The actual binary detection logic is in the convert() method.
• Flag definitions (crates/core/flags/defs.rs): Command-line flag parsing and validation

Troubleshooting¶

Binary files are unexpectedly skipped¶

If files you expect to be searched are being skipped:

1. Check if the file is being detected as binary: Use --debug to see which files are classified as binary

   rg --debug "pattern" 2>&1 | grep -i binary
   

2. Force searching with --binary: If you want to search the file anyway and see warnings

   rg --binary "pattern"
   

3. Disable binary detection entirely: Use --text if you know the file contains text but has NUL bytes

   rg --text "pattern"
   

Performance impact of --text vs --binary¶

Recommendation: Use --binary for mixed directories. Only use --text when you're certain the files contain text data with NUL bytes.

Terminal corruption after using --text¶

If your terminal displays garbage after searching binary files with --text:

1. Reset your terminal:

   reset
   # or
   tput reset
   

2. Prevent corruption by redirecting output:

   rg --text "pattern" *.bin > results.txt 2>&1
   

3. Use --binary instead: Safer alternative that shows warnings without binary content

   rg --binary "pattern" *.bin
   

See Also¶

• Binary Data Overview - Main binary data handling documentation
• File Encoding - Character encoding handling
• Automatic Filtering - File filtering and type detection