guides / basic-usage

Basic Usage

Learn the fundamental gnaw commands and patterns for everyday use.

Getting Started

Simple Pattern Search

The most basic gnaw usage is searching for a pattern in a file:

gnaw "pattern" file.txt

```bash Terminal gnaw "ERROR" test.log ```

4: 2023-03-15 12:34:58,789 ERROR django.request: Internal Server Error: /api/v1/data/
7: 2023-03-15 12:35:12,234 ERROR auth.middleware: Authentication failed for user 12345

Recursive Directory Search

Search through directories and subdirectories:

gnaw -r "pattern" ./logs/

```bash Terminal gnaw -r "ERROR" ./logs/ ```

logs/app.log:4: 2023-03-15 12:34:58,789 ERROR django.request: Internal Server Error
logs/error.log:1: 2023-03-15 12:35:12,234 ERROR auth.middleware: Authentication failed

Essential Options

Case Insensitive Search

gnaw -i "error" test.log

Show Line Numbers

gnaw -n "pattern" file.txt

Count Matches

gnaw -c "pattern" file.txt

Show Only Filenames

# Files with matches
gnaw -l "pattern" ./logs/

# Files without matches
gnaw -L "pattern" ./logs/

Context Options

Show Context Around Matches

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

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

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

```bash Terminal gnaw -C 2 "ERROR" test.log ```

2: 2023-03-15 12:34:55,123 INFO app.startup: Application starting
3: 2023-03-15 12:34:56,456 INFO app.config: Loading configuration
4: 2023-03-15 12:34:58,789 ERROR django.request: Internal Server Error: /api/v1/data/
5: 2023-03-15 12:34:59,012 INFO app.recovery: Attempting recovery
6: 2023-03-15 12:35:00,345 INFO app.recovery: Recovery successful
--
8: 2023-03-15 12:35:10,123 INFO app.request: Processing request
9: 2023-03-15 12:35:12,234 ERROR auth.middleware: Authentication failed for user 12345
10: 2023-03-15 12:35:13,456 INFO app.response: Sending error response

Advanced Pattern Matching

Extended Regular Expressions

gnaw -E "ERROR|WARN" test.log

Fixed String Search

gnaw -F "exact string" file.txt

Multiple Patterns

gnaw -e "ERROR" -e "WARN" test.log

Input Sources

Piped Input

cat test.log | gnaw "ERROR"

Multiple Files

gnaw "pattern" file1.txt file2.txt file3.txt

File Globbing

gnaw "pattern" *.log
gnaw "pattern" logs/*.log

Output Options

JSON Output

gnaw --json "ERROR" test.log

{
  "search_term": "ERROR",
  "time_taken": "0.123s",
  "results": [
    {
      "file_name": "test.log",
      "line_number": 4,
      "line": "2023-03-15 12:34:58,789 ERROR django.request: Internal Server Error"
    }
  ]
}

Streaming Output

gnaw --stream "pattern" large_file.log

Raw Count

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

Common Use Cases

Log Analysis

# Find all errors in today's logs
gnaw "ERROR" /var/log/app-$(date +%Y-%m-%d).log

# Count warnings
gnaw -c "WARN" /var/log/app.log

# Find errors with context
gnaw -C 3 "ERROR" /var/log/app.log

Code Search

# Find function definitions
gnaw -n "def " *.py

# Find TODO comments
gnaw -n "TODO" src/

# Find imports
gnaw -n "import " *.py

File Discovery

# Find files containing a pattern
gnaw -l "database" src/

# Find files without a pattern
gnaw -L "test" src/

Ignore Functionality

gnaw automatically respects ignore files:

.gitignore files
.gnawignore files
.ignore files
Hidden files and directories
Binary files

Custom Ignore Rules

Create a .gnawignore file:

# Ignore log files
*.log

# Ignore node_modules
node_modules/

# Ignore build directories
build/
dist/

Disable Ignore Rules

gnaw --no-ignore "pattern" .

Performance Tips

More specific patterns are faster than broad ones. Use directory flags to limit search scope when possible. Simple patterns are faster than complex regular expressions.

Troubleshooting

- Check if files are being ignored - Verify pattern syntax - Try case-insensitive search with `-i` - Check file permissions - Use `sudo` if necessary - Verify directory access - Use more specific patterns - Limit search scope - Check ignore rules

Next Steps

gnaw is designed to be a drop-in replacement for grep. Most grep commands work with gnaw with enhanced performance and features.