rgrep

A fast, powerful grep-like tool written in Rust with extended features including regex support, recursive search, and context display.

Table of Contents

• Installation
• Quickstart
• CLI Usage Examples
• Main Options/Flags
• Exit Codes
• Project Structure
• Testing
• Benchmarks
• Related Documents
• Contributing
• License

Installation

Option 1: Download Prebuilt Binary (Recommended)

Download the latest v1 binary from GitHub Releases:

# Download the binary for your platform
curl -L https://github.com/manwwe/rgrep/releases/download/v1.0.0/rgrep-linux-x64 -o rgrep

# Make it executable
chmod +x rgrep

# Move to PATH (optional)
sudo mv rgrep /usr/local/bin/

# Verify installation
rgrep --version

# Optional: Verify checksum
curl -L https://github.com/f4ga/rgrep/releases/download/v1.0.0/checksums.txt
sha256sum rgrep  # Compare with published checksum

Option 2: Build from Source

Requires Rust 1.80+ and cargo:

git clone https://github.com/f4ga/rgrep.git
cd rgrep
cargo build --release
./target/release/rgrep --version

The binary will be available at target/release/rgrep.

Quickstart

# Basic search
rgrep "error" file.txt

# Case-insensitive search
rgrep -i "ERROR" file.txt

# Invert match (show non-matching lines)
rgrep -v "debug" file.txt

# Count matching lines
rgrep -c "warning" *.log

# Regex search
rgrep -E "test[0-9]+" file.txt
rgrep -Ei "error.*failed" file.txt

# Recursive search with exclusions
rgrep -r "TODO" src/
rgrep -r --exclude "*.log" --exclude-dir "target" "pattern" .

# Colored output
rgrep --color=always "pattern" file.txt

# Show only filenames
rgrep -l "main" *.rs        # Files with matches
rgrep -L "copyright" *.rs   # Files without matches

# Context lines
rgrep -A 2 "error" file.txt   # 2 lines after
rgrep -B 2 "error" file.txt   # 2 lines before
rgrep -C 2 "error" file.txt   # 2 lines around

# Line numbers
rgrep -n "fn main" src/main.rs

# Search stdin
echo "test data" | rgrep "data"
rgrep "pattern" -  # Explicit stdin

CLI Usage Examples

Complex Searches

# Multi-flag combinations
rgrep -Ei -C 2 -r --exclude "*.tmp" "error.*failed" /var/log/

# Count errors in log files
rgrep -c -i "error" /var/log/*.log

# Find files without copyright notices
rgrep -L "copyright" src/*.rs

# Regex with line numbers and colors
rgrep -En --color=always "fn \w+" src/main.rs

Recursive Search Examples

# Search all Rust files recursively
rgrep -r "unsafe" src/

# Exclude common build artifacts
rgrep -r --exclude-dir "target" --exclude-dir ".git" "TODO" .

# Search with multiple exclusions
rgrep -r --exclude "*.log" --exclude "*.tmp" --exclude-dir "node_modules" "pattern" .

Main Options/Flags

Flag	Long Form	Description
-i	--ignore-case	Case-insensitive matching
-n	--line-number	Show line numbers
-v	--invert-match	Show non-matching lines
-c	--count	Count matching lines
-E	--extended-regexp	Use regular expressions
-r	--recursive	Search directories recursively
-l	--files-with-matches	Show only filenames with matches
-L	--files-without-match	Show only filenames without matches
-A NUM	--after-context=NUM	Show NUM lines after matches
-B NUM	--before-context=NUM	Show NUM lines before matches
-C NUM	--context=NUM	Show NUM lines around matches
	--color=MODE	Color output (never/always/auto)
	--exclude=PATTERN	Exclude files matching glob pattern
	--exclude-dir=PATTERN	Exclude directories matching pattern

Exit Codes

Code	Meaning
0	Success - matches found
1	No matches found
2	Invalid arguments or usage error
3	File I/O or system error

Project Structure

rgrep/
├── src/
│   ├── main.rs          # Entry point and CLI handling
│   ├── lib.rs           # Main library exports
│   ├── app.rs           # Core application logic
│   ├── cli.rs           # Command-line interface definition
│   ├── search.rs        # Search algorithms and matchers
│   ├── walker.rs        # File system traversal
│   ├── io.rs            # I/O utilities and file handling
│   └── errors.rs        # Error types and exit codes
├── tests/
│   ├── parse.rs         # CLI parsing tests
│   └── search.rs        # Search functionality tests
├── benches/
│   ├── search_bench.rs  # Performance benchmarks
│   └── README_benchmarks.md  # Benchmark documentation
├── FEATURES.md          # Extended feature documentation
├── BENCHMARKS.md        # Benchmark results and usage
└── CLAUDE.md           # Development guidance for Claude

Testing

Run the full test suite:

cargo test

Run specific test modules:

cargo test parse     # CLI parsing tests
cargo test search    # Search functionality tests

Benchmarks

Run synthetic performance benchmarks:

# Run all benchmarks
cargo bench

# Run specific benchmark category
cargo bench synthetic_search

# Faster execution for development
CRITERION_SAMPLES=20 cargo bench

# View detailed HTML reports
open target/criterion/report/index.html

The benchmark suite measures CPU-focused performance using synthetic in-memory datasets to eliminate I/O variability. Current performance on synthetic data (1000 lines):

• Literal search: ~380-395 MiB/s
• Case-insensitive: ~300-310 MiB/s
• Regex search: ~800-840 MiB/s
• Inverted search: ~370-380 MiB/s

See BENCHMARKS.md for detailed benchmark results and configuration options.

Related Documents

• FEATURES.md - Complete feature documentation with examples
• BENCHMARKS.md - Benchmark results and performance analysis

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (cargo test)
5. Run benchmarks if performance-related (cargo bench)
6. Commit your changes (git commit -am 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.