___________.__            .___    __________  _________
\_   _____/|__| ____    __| _/____\______   \/   _____/
 |    __)  |  |/    \  / __ |/ __ \|       _/\_____  \
 |     \   |  |   |  \/ /_/ \  ___/|    |   \/        \
 \___  /   |__|___|  /\____ |\___  >____|_  /_______  /
     \/            \/      \/    \/       \/        \/

A simpler way to find files and search content from the command line.

I live in the terminal and I got sick of typing find . -type f -name "*.py" -exec grep -iH "..." {} \; every day. This is what I use these days and you should get involved.

• Documentation - Complete user guide, examples, and reference
• Performance Benchmarks - See how it compares
• Contributing Guide - Help make it better
• Changelog - What's new
• Architecture Decisions - Why things work the way they do

I wanted to learn Rust. I live in the command line. I needed a problem to solve. While I was typing the cumbersome find command above for maybe the 1,000,000th time, I decided I could do better.

This tool is faster and simpler:

# The old way
find . -type f -name "*.py" -exec grep -iH "TODO" {} \;

# The new way
finder . -f ".py" -s "TODO"

What you get:

• Simple interface: -f finds files, -s searches content
• Colored output by default (matches highlighted, easy to scan)
• Multiple output modes (JSON, count-only, files-only)
• Fast enough for daily use (streaming, efficient)
• Single binary, no dependencies

Find all Python files:

finder -f ".py"

Search for "TODO" in all files:

finder -s "TODO"

Find TODOs in Python files in a library:

finder src/ -f ".py" -s "TODO"

Case-insensitive search:

finder -s "error" -i

Get just the file paths (like grep -l):

finder -s "TODO" -l

Output as JSON for scripting:

finder -s "error" --json | jq '.[] | .path'

That's it. The output is colored by default when you're in a terminal, and switches to plain text when piped. You can force colors with --colour or disable them with --no-colour.

Download the latest release for your platform from GitHub Releases:

wget https://github.com/ydkadri/finders/releases/latest/download/finder-<version>-<arch>.tar.gz

Available architectures:

• x86_64-linux - Linux (x86_64)
• aarch64-macos - macOS (Apple Silicon)
• x86_64-macos - macOS (Intel)
• x86_64-windows - Windows (use .zip instead of .tar.gz)

Extract and install:

tar -xzf finder-<version>-<arch>.tar.gz  # or unzip for Windows
sudo mv finder /usr/local/bin/           # or add to PATH on Windows

Verify checksum (optional):

wget https://github.com/ydkadri/finders/releases/latest/download/finder-<version>-<arch>.tar.gz.sha256
sha256sum -c finder-<version>-<arch>.tar.gz.sha256

If you have Rust installed:

cargo install finders

finder --version

This project uses just as a command runner for common development tasks.

# Quick development workflow
just dev          # Format, lint, and test library (fast feedback)

# Run tests
just test         # All tests (with serialized execution)
just watch        # Auto-run tests on file changes

# Code quality
just lint         # Format check + clippy
just fmt          # Format code

# Coverage and benchmarks
just coverage     # Generate HTML coverage report
just bench        # Run benchmarks

# Pre-commit checks
just pre-commit   # Run all checks before committing

# Simulate CI locally
just ci           # Run all CI checks

See docs/justfile-guide.md for the complete list of commands and detailed usage.

Usage: finder [OPTIONS] [PATH]

Arguments:
  [PATH]  Optional path to operate on, defaults to CWD

Options:
  -f, --file-pattern <FILE_PATTERN>      File pattern to filter results
  -s, --search-pattern <SEARCH_PATTERN>  Search pattern to match in result files
  -r, --regex-pattern <REGEX_PATTERN>    Regex pattern to match in result files
  -i, --case-insensitive                 Flag for case insensitive search
  -v, --verbose                          Verbose output details unreadable files
      --colour                           Enable coloured output (force on)
      --no-colour                        Disable coloured output (force off)
  -l, --files-with-matches               Output only file paths with matches (like grep -l)
  -c, --count                            Output match count per file (like grep -c)
      --json                             Output results as JSON
  -j, --threads <THREADS>                Number of threads to use (0 = auto-detect) [default: 0]
  -h, --help                             Print help
  -V, --version                          Print version

FindeRS supports colored output for better readability:

• File paths: Green
• Line numbers: Cyan
• Matches: Bold white on blue background

Colors auto-detect when outputting to a terminal and disable when piped. Control with:

# Force colors on (useful for piping to less)
finder . -s "pattern" --colour | less -R

# Force colors off
finder . -s "pattern" --no-colour

# Respect NO_COLOR environment variable
NO_COLOR=1 finder . -s "pattern"

Respects NO_COLOR and CLICOLORS standards.

Standard output (default):

finder . -s "TODO"
# Output: path:line: content
# src/lib.rs:42: // TODO: implement this

Files-only mode (-l):

finder . -s "TODO" -l
# Output: file paths only
# src/lib.rs
# src/main.rs

Count mode (-c):

finder . -s "FIXME" -c
# Output: path:count
# src/lib.rs:3
# src/main.rs:7

JSON mode (--json):

finder . -s "error" --json | jq
# Output: structured JSON
[
  {
    "path": "src/lib.rs",
    "matches": [
      {"line": 42, "content": "error handling"}
    ]
  }
]

⚠️ Breaking Changes:

• Output format changed from 4: /path/file.rs content to /path/file.rs:4: content
• This matches industry standards (grep/ripgrep) for better tool integration
• If you have scripts parsing finder output, they'll need updates

New Features:

• ✨ Colored output with match highlighting
• ✨ Multiple output modes (-l, -c, --json)
• ✨ Environment variable support for color control

See CHANGELOG.md for full details and migration guide.

FindeRS is designed for performance with:

• Parallel file processing using Rayon (30-60% faster on medium/large repos)
• Streaming file processing using 8KB chunks
• Line-by-line searching to minimize memory usage
• Efficient pattern matching with both simple string search and regex support
• Multi-core utilization (verified ~600% CPU on 8-core machines)

Internal Benchmarks: Run automatically on every pull request and merge to main. View the latest results in the Actions tab.

Key benchmark categories:

• searcher_search_line: Tests case-sensitive and case-insensitive string matching
• regex_searcher_search_line: Tests regex pattern matching performance
• searcher_search_content: Tests multi-line content searching
• file_finder: Tests file discovery with and without patterns

Comparison Benchmarks: See how finder performs against find+grep and ripgrep at ydkadri.github.io/finders/benchmarks

Comparison benchmarks test 6 scenarios:

• 3 repository sizes: small (~100 files), medium (~1K files), large (~5K files)
• 2 search patterns: common (found in ~50% of files), rare (found in 1 file)

Benchmarks run automatically on new releases and can be triggered manually via GitHub Actions.

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

Key points:

• Experiment and iterate - try things, see what works, throw away what doesn't
• Explain why changes matter, not just what changed
• Follow Rust best practices and conventions

Releases are semi-automated through GitHub Actions:

1. Update version in Cargo.toml and CHANGELOG.md
2. Merge version bump PR to main
3. Manually create and push git tag: git tag -a vX.Y.Z -m "Release vX.Y.Z" && git push origin vX.Y.Z
4. The release workflow automatically:
   • Builds binaries for all platforms
   • Creates a GitHub release with binaries
   • Publishes to crates.io
   • Triggers benchmark workflow with updated results

See CLAUDE.md for detailed release process including hotfix procedures.

MIT License - see LICENSE for details.