perg

A fast, feature-rich text search tool similar to grep, written in Rust.

perg is a modern implementation of the classic grep utility, designed for speed and ease of use. It supports regular expressions, recursive directory searching, and various output formatting options.

Features

Fast text searching with regular expression support
Recursive directory search with the -r flag
Case-insensitive matching with the -i flag
Line number display with the -n flag
Filename display with the -H flag
Invert match (show non-matching lines) with the -v flag
Files with/without matches listing with -l/-L flags
Count matching lines with the -c flag
Show only matching parts with the -o flag
Context lines with -B (before), -A (after), and -C (around) flags
Limit matches with the -m flag
Colorized output with the --color flag
Multiple file/directory support
Proper error handling and exit codes

❯ perg --help
A fast, feature-rich text search tool similar to grep, written in Rust

Usage: perg [OPTIONS] <PATTERN> [PATH]...

Arguments:
  <PATTERN>  Pattern to search for (supports regular expressions)
  [PATH]...  Files or directories to search in

Options:
  -i, --ignore-case
          Perform case insensitive matching
  -n, --line-number
          Show line numbers
  -H, --with-filename
          Show filenames
  -r, --recursive
          Recursively search directories
  -s, --no-messages
          Suppress error messages about inaccessible files
  -v, --invert-match
          Invert match: show lines that do NOT match the pattern
  -l, --files-with-matches
          Only show filenames that contain matches
  -L, --files-without-match
          Only show filenames that do NOT contain matches
  -c, --count
          Print a count of matching lines for each input file
  -B, --before-context <BEFORE_CONTEXT>
          Print NUM lines of leading context before matching lines [default: 0]
  -A, --after-context <AFTER_CONTEXT>
          Print NUM lines of trailing context after matching lines [default: 0]
  -C, --context <CONTEXT>
          Print NUM lines of output context [default: 0]
  -m, --max-count <MAX_COUNT>
          Stop reading a file after NUM matching lines
  -o, --only-matching
          Print only the matched (non-empty) parts of a matching line
  -h, --help
          Print help
  -V, --version
          Print version

Usage

A test.md file is included in this repo for testing:

$ cat test.md
hello world hi world bye world end of file Title

Basic Usage

Search for a pattern in a file:

$ perg hello test.md
hello world

Advanced Features

Line numbers:

$ perg -n world test.md
1:hello world
2:hi world
3:bye world

Case insensitive search:

$ perg -i title test.md
Title

Invert match (show lines that DON'T match):

$ perg -v world test.md
end of file
Title

Recursive directory search:

perg -r "pattern" /path/to/directory

Show filenames with matches:

$ perg -l world test.md
test.md

Show filenames without matches:

$ perg -L world test.md
# (shows files that don't contain "world")

Count matching lines:

$ perg -c world test.md
test.md:2

Show only matching parts:

$ perg -o 'h[ei]' test.md
hello
hi

Context lines around matches:

# Show 1 line before and after each match
$ perg -B 1 -A 1 'pattern' file.txt

# Show 2 lines of context around matches
$ perg -C 2 'pattern' file.txt

Limit number of matches:

$ perg -m 2 'pattern' file.txt
# Show only the first 2 matches

Colorized output:

$ perg --color=always 'pattern' file.txt
# Show matches with color highlighting
$ perg --color=never 'pattern' file.txt  
# Never show colors (plain text)
$ perg --color=auto 'pattern' file.txt
# Show colors automatically based on terminal support (default)

Multiple files:

$ perg -H pattern file1.txt file2.txt
file1.txt:matching line
file2.txt:another match

Regular expressions:

$ perg "h[ei]" test.md
hello world
hi world

$ perg "hello|bye" test.md
hello world
bye world

$ perg "^(be)" test.md
bye world
end of file

Combined options:

perg -r -i -n "error" /var/log/

Installation

From Crates.io

Using Cargo via rustup:

curl https://sh.rustup.rs -sSf | sh

Then install perg:

cargo install perg

Note: If you see "cargo command not found", restart your terminal and run the install command again.

From Source

Clone the repository and build:

git clone https://github.com/vinhnx/perg.git
cd perg
cargo build --release
./target/release/perg --help

Exit Codes

0: Success, matches found (or no matches when using -L)
1: File not found or other I/O errors
2: Invalid regular expression

Project Structure

This project is organized as follows:

src/
├── main.rs      # CLI entry point
├── lib.rs       # Library exports
├── cli.rs       # Command-line argument parsing
├── search.rs    # Core search functionality
├── error.rs     # Error types and handling
└── ...

Development

This project was created as a learning exercise for Rust programming. It demonstrates:

Modern Rust development practices
CLI application development with clap
Error handling patterns
Unit and integration testing
Documentation with rustdoc

Running Tests

cargo test                    # Run all tests
cargo test --test integration_test  # Run integration tests only
cargo test search::tests      # Run specific test module

Benchmarks

The tool is optimized for performance and can handle large files and directories efficiently.

Contributing

Contributions are welcome! Please feel free to:

Report bugs
Suggest features
Submit pull requests
Improve documentation

License

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

What's with the name?

Glad you asked, perg is just the reversed spelling of grep! 🦀

Rust Resources 🦀

Rust continues to be one of the most loved programming languages according to Stack Overflow surveys. :gift:

perg 0.8.0