Output Formatting

gnaw provides flexible output formatting options for different use cases.

Output Formats

Default Format

Standard grep-like output with enhanced features:

gnaw "ERROR" test.log

4: 2023-03-15 12:34:58,789 ERROR django.request: Internal Server Error: /api/v1/data/

JSON Format

Structured output for programmatic consumption:

gnaw --json "ERROR" test.log

{
  "search_term": "ERROR",
  "time_taken": "0.123s",
  "results": [
    {
      "file_name": "logs/app.log",
      "line_number": 42,
      "line": "2023-03-15 12:34:58,789 ERROR django.request: Internal Server Error: /api/v1/data/"
    }
  ]
}

Agent Mode Output

Rich, contextual results for semantic search:

gnaw agent ask "authentication functions"

Query: authentication functions

→ src/auth.rs (score: 0.95)
  Lines 15-25
  • Function definition matches query
  • Contains authentication keywords
  • High semantic similarity
  pub fn authenticate_user(token: &str) -> Result<User, AuthError> {
      // Authentication logic here
  }

Formatting Options

Context Display

Show surrounding lines for better context:

# Show 2 lines before and after
gnaw -C 2 "ERROR" test.log

# Show 3 lines after
gnaw -A 3 "ERROR" test.log

# Show 1 line before
gnaw -B 1 "ERROR" test.log

Line Numbers and Filenames

# Show line numbers
gnaw -n "pattern" file.txt

# Show filenames
gnaw -H "pattern" file.txt

# Show both (like grep -Hn)
gnaw -Hn "pattern" file.txt

File-based Output

# Show only filenames with matches
gnaw -l "pattern" ./logs/

# Show only filenames without matches
gnaw -L "pattern" ./logs/

# Count matches per file
gnaw -c "pattern" ./logs/

Configuration

Output Format Settings

# gnaw.toml
output_format = "ascii_box"  # or "json"
color = true
match_color = "cyan"

Color Customization

Available colors:

• red, yellow, green, blue, magenta, cyan, white

# gnaw.toml
color = true
match_color = "cyan"

Advanced Formatting

Custom Separators

When showing context, gnaw uses -- as a separator between non-contiguous groups, just like grep.

Streaming Output

Get results as they're found:

gnaw --stream "pattern" large_file.log

Raw Count Output

For scripting and automation:

gnaw --raw -c "pattern" file.txt

Integration Examples

Shell Scripts

#!/bin/bash
# Count errors in log files
ERROR_COUNT=$(gnaw --raw -c "ERROR" /var/log/app.log)
if [ "$ERROR_COUNT" -gt 10 ]; then
    echo "High error count: $ERROR_COUNT"
fi

JSON Processing

# Get structured data for processing
gnaw --json "ERROR" test.log | jq '.results[].line_number'

CI/CD Integration

# Check for TODO comments in code
if gnaw -l "TODO" src/; then
    echo "Found TODO comments in code"
    exit 1
fi

Performance Considerations

JSON output has slight performance overhead due to serialization. Color output may be slower on some terminals. Disable for maximum speed. Streaming output provides real-time results but may be slower overall.

Best Practices

1. Use JSON for Automation: Structured output is easier to parse programmatically
2. Disable Color in Scripts: Set color = false in configuration for scripts
3. Leverage Context: Use -C, -A, -B for better understanding of matches
4. Combine Options: Use multiple formatting options together for comprehensive output

For maximum compatibility with existing tools, gnaw's default output format closely matches grep's behavior while adding enhanced features.