perg

https://crates.io/crates/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 🦀

• The Rust Programming Language Book
• Rust by Example
• Rustlings - Great for learning Rust

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