Introduction

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.

What is FindeRS?

FindeRS (finder) is a command-line tool that simplifies file searching. It combines the power of find and grep with a cleaner, more intuitive interface.

Instead of this:

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

You write this:

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

Key Features

Simple interface: -f finds files, -s searches content
Colored output: Matches highlighted, easy to scan
Multiple output modes: JSON, count-only, files-only
Fast and efficient: Streaming file processing
Single binary: No dependencies, just download and run

Quick Example

Search for “TODO” comments in all Python files:

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

Output:

src/lib.rs:42: // TODO: implement this feature
src/main.rs:15: // TODO: add better error handling

Why Choose FindeRS?

Learnable: Simple flags, no complex syntax
Practical: Built for daily use, not edge cases
Predictable: Sensible defaults, colored output when needed
Fast enough: Streaming processing, efficient search algorithms

Next Steps

Install FindeRS on your system
Follow the Quick Start guide
Explore common use cases

Getting Help

GitHub Issues - Bug reports and feature requests
Contributing Guide - Help make it better
Troubleshooting - Common problems and solutions

Installation

There are several ways to install FindeRS. Choose the method that works best for you.

From Pre-built Binaries (Recommended)

Download the latest release for your platform from GitHub Releases:

# Linux (x86_64)
wget https://github.com/ydkadri/finders/releases/latest/download/finder-<version>-x86_64-linux.tar.gz

# macOS (Apple Silicon)
wget https://github.com/ydkadri/finders/releases/latest/download/finder-<version>-aarch64-macos.tar.gz

# macOS (Intel)
wget https://github.com/ydkadri/finders/releases/latest/download/finder-<version>-x86_64-macos.tar.gz

# Windows
wget https://github.com/ydkadri/finders/releases/latest/download/finder-<version>-x86_64-windows.zip

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

From Source (via Cargo)

If you have Rust installed:

cargo install finders

This compiles from source and installs the binary in ~/.cargo/bin/. Make sure this directory is in your PATH.

From Source (Manual Build)

# Clone the repository
git clone https://github.com/ydkadri/finders.git
cd finders

# Build in release mode
cargo build --release

# The binary will be at target/release/finder
sudo cp target/release/finder /usr/local/bin/

Verify Installation

After installing, verify it works:

finder --version

You should see output like:

finder 3.0.0

Updating

Binary Installation

Download and install the latest release following the same steps above.

Cargo Installation

cargo install finders --force

Uninstalling

Binary Installation

sudo rm /usr/local/bin/finder

Cargo Installation

cargo uninstall finders

Next Steps

Follow the Quick Start guide to learn the basics
Explore common use cases
Check the CLI Reference for all available options

Quick Start

Get started with FindeRS in minutes. This guide covers the most common usage patterns.

Basic Concepts

FindeRS has two main operations:

Finding files - Filter by filename pattern with -f
Searching content - Search for text patterns with -s

You can use them separately or together.

Find Files by Pattern

Find all Python files in the current directory:

finder -f ".py"

Find all Markdown files:

finder -f ".md"

Find files in a specific directory:

finder src/ -f ".rs"

Search Content

Search for “TODO” in all files:

finder -s "TODO"

Case-insensitive search:

finder -s "error" -i

Combine Both

Find “TODO” comments in Python files:

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

Find “FIXME” in Rust files within the src directory:

finder src/ -f ".rs" -s "FIXME"

Output Modes

Standard Output (Default)

Shows file path, line number, and matching content:

finder -s "TODO"

Output:

src/lib.rs:42: // TODO: implement this feature
src/main.rs:15: // TODO: add better error handling

Files Only (`-l`)

List only the file paths (like grep -l):

finder -s "TODO" -l

Output:

src/lib.rs
src/main.rs

Count Matches (`-c`)

Show match count per file (like grep -c):

finder -s "TODO" -c

Output:

src/lib.rs:3
src/main.rs:2

JSON Output (`--json`)

Structured output for scripts:

finder -s "error" --json

Output:

[
  {
    "path": "src/lib.rs",
    "matches": [
      {"line": 42, "content": "handle error cases"}
    ]
  }
]

Working with Colors

Colors are automatic - on by default when outputting to a terminal, off when piping.

Force colors on (useful with less -R):

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"

Using with Other Tools

Pipe to jq

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

Count total matches

finder -s "TODO" -c | awk -F: '{sum+=$2} END {print sum}'

Find and open in editor

vim $(finder -f "config" -l)

Common Patterns

Find configuration files

finder -f "config"

Search for API keys (be careful!)

finder -s "api_key" -i

Find large log files

finder -f ".log" | xargs ls -lh

Search in specific file types

finder -f ".ts" -s "interface"  # TypeScript
finder -f ".go" -s "func"        # Go
finder -f ".py" -s "class"       # Python

Next Steps

Explore common use cases in detail
Check the CLI Reference for all options
Learn about color configuration
See advanced patterns

CLI Reference

Complete reference for all FindeRS command-line options.

Synopsis

finder [OPTIONS] [PATH]

Arguments

`[PATH]`

Optional path to operate on. Defaults to the current working directory.

Examples:

finder              # Search in current directory
finder src/         # Search in src/ directory
finder ../project/  # Search in ../project/ directory

Options

File Filtering

`-f, --file-pattern <PATTERN>`

Filter files by pattern in filename.

Examples:

finder -f ".rs"     # All Rust files
finder -f "test"    # Files containing "test" in name
finder -f ".config" # All config files

Content Searching

`-s, --search-pattern <PATTERN>`

Search for a literal string pattern in file contents.

Examples:

finder -s "TODO"            # Find all TODOs
finder -s "function main"   # Find main functions
finder -s "api_key"         # Find API key references

`-r, --regex-pattern <PATTERN>`

Search using a regular expression pattern.

Examples:

finder -r "TODO|FIXME"          # Find TODOs or FIXMEs
finder -r "fn \w+\("            # Find Rust functions
finder -r "[0-9]{3}-[0-9]{4}"   # Find phone numbers

`-i, --case-insensitive`

Make search case-insensitive.

Examples:

finder -s "error" -i     # Matches "Error", "ERROR", "error"
finder -r "todo" -i      # Case-insensitive regex search

Output Control

`-l, --files-with-matches`

Output only file paths that contain matches (like grep -l).

Example:

finder -s "TODO" -l

Output:

src/lib.rs
src/main.rs

`-c, --count`

Output match count per file (like grep -c).

Example:

finder -s "error" -c

Output:

src/lib.rs:5
src/main.rs:2

`--json`

Output results in JSON format for programmatic processing.

Example:

finder -s "error" --json

Output:

[
  {
    "path": "src/lib.rs",
    "matches": [
      {"line": 42, "content": "handle error"}
    ]
  }
]

Color Control

`--colour`

Force colored output on (useful when piping to less -R).

Example:

finder -s "pattern" --colour | less -R

`--no-colour`

Force colored output off.

Example:

finder -s "pattern" --no-colour > results.txt

Note: Colors auto-detect by default - on for terminals, off for pipes.

Verbosity

`-v, --verbose`

Show verbose output including files that couldn’t be read.

Example:

finder -s "pattern" -v

Information

`-h, --help`

Print help information and exit.

finder --help

`-V, --version`

Print version information and exit.

finder --version

Examples

Basic Usage

# Find Python files
finder -f ".py"

# Search for TODO in all files
finder -s "TODO"

# Find TODOs in Python files
finder -f ".py" -s "TODO"

Advanced Usage

# Case-insensitive regex search in TypeScript files
finder -f ".ts" -r "interface \w+" -i

# Get JSON output for processing
finder -s "error" --json | jq '.[] | .path'

# Count all TODOs across the project
finder -s "TODO" -c | awk -F: '{sum+=$2} END {print sum}'

# Find files and open in vim
vim $(finder -f "config" -l)

Working with Directories

# Search in specific directory
finder src/ -s "TODO"

# Search in multiple patterns
finder -f ".rs" -s "TODO" && finder -f ".md" -s "TODO"

# Search specific directory with file type
finder src/ -f ".rs" -s "TODO"

Environment Variables

FindeRS respects standard color environment variables:

NO_COLOR - Disable colors entirely
CLICOLOR - Enable/disable color support
CLICOLOR_FORCE - Force colors on

See Color Configuration for details.

Exit Codes

0 - Success, matches found
1 - Error occurred
0 - No matches found (not an error)

Output Modes

FindeRS supports multiple output modes to suit different use cases.

Standard Output (Default)

Shows file path, line number, and matching content.

finder -s "TODO"

Output:

src/lib.rs:42: // TODO: implement this
src/main.rs:15: // TODO: add error handling

Files Only Mode (`-l`)

Lists only file paths containing matches, similar to grep -l.

finder -s "TODO" -l

Output:

src/lib.rs
src/main.rs

Count Mode (`-c`)

Shows the number of matches per file, similar to grep -c.

finder -s "TODO" -c

Output:

src/lib.rs:3
src/main.rs:2

JSON Mode (`--json`)

Structured JSON output for programmatic processing.

finder -s "error" --json

Output:

[
  {
    "path": "src/lib.rs",
    "matches": [
      {"line": 42, "content": "handle error cases"},
      {"line": 87, "content": "return error result"}
    ]
  }
]

Combining Modes

Output modes are mutually exclusive. Use one at a time:

# ✓ Valid
finder -s "TODO" -l
finder -s "TODO" -c
finder -s "TODO" --json

# ✗ Invalid (last one wins)
finder -s "TODO" -l -c

Use Cases

Standard: Interactive terminal use, reading results
Files only (-l): Piping to other commands, opening in editor
Count (-c): Statistics, understanding distribution
JSON (--json): Scripting, integration with other tools

Next Steps

Color Configuration - Customize output colors
Integration Examples - Use with other tools

Colour Configuration

FindeRS provides coloured output for better readability. This page explains how to configure and control colours.

Default Behaviour

Colours are automatic by default:

On when outputting to a terminal (TTY)
Off when piping to another command or file

This “just works” for most use cases without any configuration.

Colour Scheme

When colours are enabled:

File paths: Green
Line numbers: Cyan
Match highlights: Bold white on blue background

Force Colours On

Use --colour to force colours on, even when piping:

finder -s "pattern" --colour | less -R

The -R flag tells less to display colours correctly.

Force Colours Off

Use --no-colour to force colours off:

finder -s "pattern" --no-colour

Useful for:

Saving output to files
Ensuring plain text in scripts
Terminal compatibility issues

Priority Order

When multiple settings conflict, FindeRS uses this priority:

CLI flags (--colour or --no-colour)
NO_COLOR environment variable
CLICOLOR_FORCE environment variable
CLICOLOR environment variable
Auto-detection (default)

Examples

Force colours for paging

finder -s "TODO" --colour | less -R

Disable colours for file output

finder -s "error" --no-colour > errors.txt

Respect NO_COLOR in scripts

#!/bin/bash
export NO_COLOR=1
finder -s "pattern"  # No colours

Troubleshooting

Colors don’t work in my terminal

Check your terminal supports ANSI colours
Try forcing colours: finder --colour
Check if NO_COLOR is set: echo $NO_COLOR

Colors show as weird characters

Your terminal doesn’t support ANSI escape codes. Use --no-colour.

Colors persist after piping

This is expected behavior. Use --no-colour if needed.

Common Use Cases

Real-world examples of how to use FindeRS effectively.

Development Workflows

Find TODOs and FIXMEs

Track technical debt across your codebase:

finder -s "TODO" -l
finder -s "FIXME" -c
finder -r "TODO|FIXME" -i

Find Configuration Files

Locate all config files in a project:

finder -f "config"
finder -f ".json" -s "database"
finder -f ".yaml" -s "api"

Search for Function Definitions

Find function definitions across different languages:

# Rust functions
finder -f ".rs" -r "fn \w+\("

# Python functions
finder -f ".py" -r "def \w+\("

# JavaScript functions
finder -f ".js" -r "function \w+\("

Code Review and Refactoring

Find All Usages

Locate all references to a variable or function:

finder -s "old_function_name"
finder -f ".rs" -s "OldStruct"

Find Deprecated APIs

Search for deprecated API usage:

finder -s "deprecated" -i
finder -r "@deprecated|DEPRECATED"

Find Error Handling

Review error handling patterns:

finder -s "unwrap()"
finder -s "expect("
finder -r "panic!|unwrap|expect"

Security and Compliance

Find Sensitive Data

⚠️ Be careful not to commit findings!

# Find potential API keys
finder -r "[A-Za-z0-9]{32,}" -i

# Find passwords in config
finder -s "password" -i -f ".env"

# Find secrets
finder -r "secret|token|key" -i

Audit Logging

Find logging statements:

finder -s "log::" -f ".rs"
finder -r "console\.(log|error|warn)"

Documentation

Find Undocumented Code

Locate public APIs without documentation:

# Rust public items without docs
finder -f ".rs" -r "pub (fn|struct|enum|trait) \w+" -l | \
  xargs -I {} sh -c 'grep -B1 "pub" {} | grep -q "///" || echo {}'

Find Broken Links

Search for old URLs or references:

finder -s "oldcompany.com"
finder -s "http://" -f ".md"

Testing

Find Test Coverage Gaps

Locate modules without tests:

# Find modules without test modules
finder -f ".rs" -l | while read f; do
  grep -q "#\[cfg(test)\]" "$f" || echo "$f"
done

Find Disabled Tests

Locate ignored or disabled tests:

finder -s "#[ignore]"
finder -s "skip_test" -i

Data Processing

Count Patterns Across Files

Get statistics about pattern usage:

# Total TODO count
finder -s "TODO" -c | awk -F: '{sum+=$2} END {print sum}'

# Files with most errors
finder -s "error" -c | sort -t: -k2 -nr | head

Extract Structured Data

Pull specific data from files:

# Extract all email addresses
finder -r "[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}" --json | \
  jq -r '.[].matches[].content'

# Extract version numbers
finder -s "version" --json | jq

Integration with Other Tools

Open Files in Editor

# Edit all files with TODOs
vim $(finder -s "TODO" -l)

# Open files with errors
code $(finder -s "ERROR" -l)

Pipe to Other Commands

# Count lines in matched files
finder -f ".rs" -l | xargs wc -l

# Find largest files
finder -f ".log" -l | xargs ls -lh | sort -k5 -hr

Create Reports

# Generate TODO report
finder -s "TODO" > todos.txt

# JSON report for CI
finder -s "FIXME" --json > fixmes.json

Performance Optimization

Find Large Files

Identify files that might slow down searches:

finder -f ".log" -l | xargs ls -lh | awk '$5 ~ /M|G/'

Profile Pattern Complexity

Test search performance:

time finder -r "complex.*regex.*pattern"
time finder -s "simple string"

Next Steps

Check Advanced Patterns for more complex use cases
See Integration Examples for CI/CD workflows
Review CLI Reference for all available options

Advanced Patterns

Complex workflows and advanced techniques for power users.

Regex Patterns

Character Classes and Quantifiers

# Find phone numbers
finder -r "\d{3}-\d{3}-\d{4}"

# Find hex colors
finder -r "#[0-9a-fA-F]{6}"

# Find email addresses
finder -r "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}"

Lookahead and Lookbehind

# Find TODO comments with ticket numbers
finder -r "TODO: \w+-\d+"

# Find functions with specific parameters
finder -r "fn \w+\([^)]*&str[^)]*\)"

Word Boundaries

# Find exact word matches
finder -r "\berror\b"

# Find variable names
finder -r "\b[a-z_][a-z0-9_]*\b"

Combining Multiple Searches

Boolean Logic

# Files with pattern A OR pattern B
finder -r "pattern_a|pattern_b"

# Multiple patterns (run separate searches)
finder -f ".rs" -s "TODO"
finder -f ".md" -s "TODO"

Working with Structured Output

Processing JSON Output

# Extract file paths only
finder -s "error" --json | jq -r '.[].path'

# Count matches per file
finder -s "TODO" --json | jq '.[] | {path: .path, count: (.matches | length)}'

# Filter by line number
finder -s "error" --json | jq '.[] | select(.matches[].line > 100)'

Building Custom Reports

# Create CSV report
finder -s "TODO" --json | jq -r '.[] | .matches[] | [.line, .content] | @csv' > report.csv

# Generate HTML report
echo "<html><body><ul>" > report.html
finder -s "TODO" -l | while read f; do
  echo "<li><a href='$f'>$f</a></li>" >> report.html
done
echo "</ul></body></html>" >> report.html

Shell Integration

Custom Aliases

Add to your .bashrc or .zshrc:

# Find and edit
alias fe='vim $(finder -l)'

# Find todos in current project
alias todos='finder -s "TODO" -c'

# Search with context
alias search='finder -s'

Functions

# Find and replace across files
find-replace() {
  local pattern="$1"
  local replacement="$2"
  finder -s "$pattern" -l | xargs sed -i "s/$pattern/$replacement/g"
}

# Count pattern occurrences
count-pattern() {
  finder -s "$1" -c | awk -F: '{sum+=$2} END {print sum}'
}

Performance Optimization

Limiting Search Scope

# Search specific directory
finder src/ -s "pattern"

# Search specific file types in directory
finder src/ -f ".rs" -s "pattern"

# Search only recently modified files
find . -mtime -7 -type f | xargs finder -s "pattern"

Parallel Processing

# Process results in parallel with xargs
finder -s "pattern" -l | xargs -P 4 -I {} sh -c 'process {}'

# GNU parallel for complex operations
finder -s "pattern" -l | parallel 'complex-operation {}'

CI/CD Integration

GitHub Actions

- name: Check for TODOs
  run: |
    if finder -s "TODO" -l > /dev/null; then
      echo "Found TODOs in code"
      finder -s "TODO"
      exit 1
    fi

GitLab CI

check-todos:
  script:
    - finder -s "TODO" > todos.txt
    - test ! -s todos.txt
  artifacts:
    paths:
      - todos.txt
    when: on_failure

Pre-commit Hooks

#!/bin/bash
# .git/hooks/pre-commit

if finder -s "NOCOMMIT" > /dev/null; then
  echo "Error: Found NOCOMMIT markers"
  finder -s "NOCOMMIT"
  exit 1
fi

Code Quality Checks

Detect Anti-patterns

# Find unwrap() in Rust
finder -f ".rs" -s "unwrap()" -c

# Find console.log in production JS
finder -f ".js" -s "console.log" | grep -v "test"

# Find SQL injection risks
finder -r "execute.*\+.*\$"

Complexity Metrics

# Find deeply nested code
finder -r "^\s{12,}" -c

# Count function definitions
finder -f ".rs" -r "fn \w+\(" -c

Documentation Generation

Extract API Documentation

# Extract all doc comments
finder -f ".rs" -r "///.*" --json | \
  jq -r '.[] | .matches[] | .content' > api-docs.txt

Generate Index

# Create module index
finder -f ".rs" -r "pub mod \w+" | \
  sed 's/.*pub mod /- /' > modules.md

Debugging and Diagnostics

Trace Code Flow

# Find all log statements
finder -r "(log|debug|info|warn|error)::" -f ".rs"

# Find panic locations
finder -s "panic!" -f ".rs"

Dependency Analysis

# Find external crate usage
finder -r "use \w+::" -f ".rs" | sort | uniq

# Find module dependencies
finder -r "mod \w+;" -f ".rs"

Working with Large Codebases

Incremental Search

# Search one directory at a time
for dir in src/*/ ; do
  echo "Searching $dir"
  finder "$dir" -s "pattern"
done

Caching Results

# Cache file list for repeated searches
finder -f ".rs" -l > rust-files.txt
cat rust-files.txt | xargs finder -s "pattern"

Next Steps

Review Common Use Cases for everyday patterns
See Integration Examples for CI/CD workflows
Check Performance for optimization tips

Integration Examples

Integrate FindeRS into your development workflows, CI/CD pipelines, and automation scripts.

Continuous Integration

GitHub Actions

Check for Forbidden Patterns

name: Code Quality Checks

on: [push, pull_request]

jobs:
  check-patterns:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install FindeRS
        run: |
          wget https://github.com/ydkadri/finders/releases/latest/download/finder-x86_64-linux.tar.gz
          tar -xzf finder-x86_64-linux.tar.gz
          sudo mv finder /usr/local/bin/
      
      - name: Check for debug statements
        run: |
          if finder -s "console.log" -l -f ".js" > /dev/null; then
            echo "❌ Found console.log statements"
            finder -s "console.log" -f ".js"
            exit 1
          fi
      
      - name: Check for TODOs
        run: |
          finder -s "TODO" -c > todo-count.txt
          cat todo-count.txt

Generate Reports

      - name: Generate TODO Report
        run: |
          echo "# TODO Report" > todo-report.md
          echo "" >> todo-report.md
          finder -s "TODO" --json | \
            jq -r '.[] | "## \(.path)\n\(.matches[] | "- Line \(.line): \(.content)")\n"' \
            >> todo-report.md
      
      - name: Upload Report
        uses: actions/upload-artifact@v4
        with:
          name: todo-report
          path: todo-report.md

GitLab CI

code-quality:
  stage: test
  image: ubuntu:latest
  before_script:
    - apt-get update && apt-get install -y wget
    - wget https://github.com/ydkadri/finders/releases/latest/download/finder-x86_64-linux.tar.gz
    - tar -xzf finder-x86_64-linux.tar.gz
    - mv finder /usr/local/bin/
  script:
    - finder -s "FIXME" > fixmes.txt
    - test ! -s fixmes.txt || (cat fixmes.txt && exit 1)
  artifacts:
    paths:
      - fixmes.txt
    when: on_failure

CircleCI

version: 2.1

jobs:
  code-quality:
    docker:
      - image: ubuntu:latest
    steps:
      - checkout
      - run:
          name: Install FindeRS
          command: |
            apt-get update && apt-get install -y wget
            wget https://github.com/ydkadri/finders/releases/latest/download/finder-x86_64-linux.tar.gz
            tar -xzf finder-x86_64-linux.tar.gz
            mv finder /usr/local/bin/
      - run:
          name: Check patterns
          command: |
            finder -s "TODO" -c

Git Hooks

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit

echo "Running pre-commit checks..."

# Check for NOCOMMIT markers
if finder -s "NOCOMMIT" > /dev/null; then
  echo "❌ Error: Found NOCOMMIT markers"
  finder -s "NOCOMMIT"
  exit 1
fi

# Check for debug statements
if finder -s "debugger" -f ".js" > /dev/null; then
  echo "❌ Error: Found debugger statements"
  finder -s "debugger" -f ".js"
  exit 1
fi

# Check for unwrap() in Rust (warning only)
unwrap_count=$(finder -s "unwrap()" -f ".rs" -c | awk -F: '{sum+=$2} END {print sum}')
if [ "$unwrap_count" -gt 0 ]; then
  echo "⚠️  Warning: Found $unwrap_count unwrap() calls"
fi

echo "✅ Pre-commit checks passed"

Pre-push Hook

#!/bin/bash
# .git/hooks/pre-push

echo "Running pre-push checks..."

# Generate security report
if finder -r "password|secret|api_key" -i --json > security-scan.json; then
  match_count=$(jq '[.[] | .matches | length] | add // 0' security-scan.json)
  if [ "$match_count" -gt 0 ]; then
    echo "⚠️  Warning: Found $match_count potential security issues"
    echo "Review security-scan.json before pushing"
  fi
fi

echo "✅ Pre-push checks complete"

Editor Integration

VS Code Tasks

Create .vscode/tasks.json:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Find TODOs",
      "type": "shell",
      "command": "finder -s TODO",
      "problemMatcher": [],
      "presentation": {
        "reveal": "always",
        "panel": "new"
      }
    },
    {
      "label": "Find in Files",
      "type": "shell",
      "command": "finder",
      "args": [
        "-s",
        "${input:searchPattern}"
      ],
      "problemMatcher": []
    }
  ],
  "inputs": [
    {
      "id": "searchPattern",
      "type": "promptString",
      "description": "Enter search pattern"
    }
  ]
}

Vim Integration

Add to .vimrc:

" Search with FindeRS and populate quickfix
command! -nargs=1 FindeRS cexpr system('finder -s ' . shellescape(<q-args>))

" Find word under cursor
nnoremap <leader>f :FindeRS <C-R><C-W><CR>

" Find TODOs
nnoremap <leader>t :FindeRS TODO<CR>

Shell Scripts

Batch Processing

#!/bin/bash
# process-matches.sh

# Find all files matching pattern and process them
finder -s "$1" -l | while read file; do
  echo "Processing $file..."
  # Your processing logic here
  process_file "$file"
done

Report Generation

#!/bin/bash
# generate-report.sh

OUTPUT_FILE="code-quality-report.html"

cat > "$OUTPUT_FILE" << 'EOF'
<!DOCTYPE html>
<html>
<head>
  <title>Code Quality Report</title>
  <style>
    body { font-family: sans-serif; margin: 2em; }
    .section { margin: 2em 0; }
    .count { font-weight: bold; color: #d73a49; }
  </style>
</head>
<body>
  <h1>Code Quality Report</h1>
EOF

echo "<div class='section'>" >> "$OUTPUT_FILE"
echo "<h2>TODOs</h2>" >> "$OUTPUT_FILE"
TODO_COUNT=$(finder -s "TODO" -c | awk -F: '{sum+=$2} END {print sum}')
echo "<p class='count'>Total: $TODO_COUNT</p>" >> "$OUTPUT_FILE"
echo "<pre>" >> "$OUTPUT_FILE"
finder -s "TODO" >> "$OUTPUT_FILE"
echo "</pre>" >> "$OUTPUT_FILE"
echo "</div>" >> "$OUTPUT_FILE"

echo "</body></html>" >> "$OUTPUT_FILE"

echo "Report generated: $OUTPUT_FILE"

Make Integration

.PHONY: check-todos check-fixmes check-patterns

check-todos:
	@echo "Checking for TODOs..."
	@finder -s "TODO" -c || true

check-fixmes:
	@echo "Checking for FIXMEs..."
	@finder -s "FIXME" -c || true

check-patterns: check-todos check-fixmes
	@echo "Checking for unwrap()..."
	@finder -f ".rs" -s "unwrap()" -c || true

check: check-patterns
	@echo "All checks complete"

Docker Integration

Dockerfile

FROM rust:latest as builder

# Install FindeRS
RUN wget https://github.com/ydkadri/finders/releases/latest/download/finder-x86_64-linux.tar.gz && \
    tar -xzf finder-x86_64-linux.tar.gz && \
    mv finder /usr/local/bin/

# Use in build steps
RUN finder -s "TODO" -c

Docker Compose

version: '3'
services:
  code-quality:
    image: ubuntu:latest
    volumes:
      - .:/workspace
    working_dir: /workspace
    command: >
      bash -c "
        apt-get update && apt-get install -y wget &&
        wget https://github.com/ydkadri/finders/releases/latest/download/finder-x86_64-linux.tar.gz &&
        tar -xzf finder-x86_64-linux.tar.gz &&
        mv finder /usr/local/bin/ &&
        finder -s TODO -c
      "

Monitoring and Alerting

Track Technical Debt

#!/bin/bash
# track-debt.sh

# Count TODOs and FIXMEs over time
DATE=$(date +%Y-%m-%d)
TODO_COUNT=$(finder -s "TODO" -c | awk -F: '{sum+=$2} END {print sum}')
FIXME_COUNT=$(finder -s "FIXME" -c | awk -F: '{sum+=$2} END {print sum}')

echo "$DATE,$TODO_COUNT,$FIXME_COUNT" >> debt-tracking.csv

# Alert if count exceeds threshold
if [ "$TODO_COUNT" -gt 100 ]; then
  echo "⚠️  Warning: TODO count exceeded 100!"
  # Send alert (email, Slack, etc.)
fi

Slack Integration

#!/bin/bash
# slack-alert.sh

WEBHOOK_URL="your-slack-webhook-url"

TODO_COUNT=$(finder -s "TODO" -c | awk -F: '{sum+=$2} END {print sum}')

curl -X POST "$WEBHOOK_URL" \
  -H 'Content-Type: application/json' \
  -d "{
    \"text\": \"Daily Code Quality Report\",
    \"blocks\": [
      {
        \"type\": \"section\",
        \"text\": {
          \"type\": \"mrkdwn\",
          \"text\": \"*TODO Count:* $TODO_COUNT\"
        }
      }
    ]
  }"

Next Steps

Explore Common Use Cases for more patterns
Check Advanced Patterns for complex workflows
Review Troubleshooting for common issues

Comparison with Other Tools

How FindeRS compares to other file and content search tools.

FindeRS is designed as a simpler alternative to find + grep combinations, with colored output and intuitive flags. It’s not trying to be the fastest tool, but rather the most convenient for daily use.

vs. find + grep

Traditional approach:

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

FindeRS approach:

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

Advantages of FindeRS:

Simpler syntax, easier to remember
Colored output by default
Single command instead of composition
Multiple output modes (JSON, count, files-only)
Consistent interface across platforms

Advantages of find + grep:

More flexible for complex queries
Universally available on Unix systems
More control over search behavior
Better for shell scripting with advanced features

When to use FindeRS:

Daily development tasks
Quick searches in projects
When you want readable, colored output
When you prefer simplicity over flexibility

When to use find + grep:

Complex directory traversal logic
Advanced grep features (context lines, binary files)
Shell scripts requiring POSIX compatibility
Systems where installing new tools is restricted

vs. ripgrep (rg)

ripgrep:

rg "TODO" --type py

FindeRS:

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

Advantages of ripgrep:

Much faster (optimized Rust implementation)
Respects .gitignore by default
Advanced features (multiline search, context)
Better regex performance
More mature and feature-complete

Advantages of FindeRS:

Simpler mental model (files vs. content)
Smaller learning curve
Explicit about what it searches
Good enough for most daily tasks

When to use ripgrep:

Large codebases (100k+ files)
Need maximum performance
Complex regex patterns
Want .gitignore integration
Replacing grep in workflows

When to use FindeRS:

Small to medium projects
Learning command-line search tools
Want explicit control over file filtering
Prefer simplicity over speed

vs. The Silver Searcher (ag)

ag:

ag "TODO" --python

FindeRS:

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

Similar trade-offs to ripgrep:

ag is faster and more feature-rich
FindeRS is simpler and more explicit
ag respects .gitignore, FindeRS searches everything
ag is better for large codebases

vs. ack

ack:

ack "TODO" --type=python

FindeRS:

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

ack has better file-type detection
FindeRS is simpler and more predictable
ack has more filtering options
FindeRS is easier to learn

Performance Comparison

Benchmark setup: 1,000 files, searching for a common pattern

Tool	Small (10 files)	Medium (1k files)	Large (10k files)
finder	2ms	9ms	43ms
find + grep	90ms	902ms	4624ms
ripgrep	5ms	8ms	22ms

Notes:

Benchmarks run on 2021 MacBook Pro M1
Results will vary based on file size and pattern complexity
FindeRS is fast enough for daily development tasks
For very large codebases (100k+ files), ripgrep is significantly faster

Feature Comparison

Feature	FindeRS	find + grep	ripgrep	ag	ack
Simple syntax	✅	❌	✅	✅	✅
Colored output	✅	❌	✅	✅	✅
Regex support	✅	✅	✅	✅	✅
JSON output	✅	❌	✅	✅	❌
.gitignore integration	❌	❌	✅	✅	✅
File type detection	❌	❌	✅	✅	✅
Multiline search	❌	✅	✅	✅	❌
Context lines	❌	✅	✅	✅	✅
Single binary	✅	❌	✅	✅	❌
Cross-platform	✅	Partial	✅	✅	✅

Choosing the Right Tool

Use FindeRS when:

You’re tired of typing complex find+grep commands
You want a simple, predictable tool
Performance is “good enough” for your use case
You prefer explicit file filtering over automatic detection

Use ripgrep when:

Performance is critical (large codebases)
You want .gitignore integration
You need advanced regex features
You’re replacing grep in existing workflows

Use find + grep when:

You need maximum flexibility
You’re writing portable shell scripts
You can’t install new tools
You need advanced find features (permissions, timestamps)

Use ag or ack when:

You want automatic file-type detection
You need .gitignore integration
Performance matters but not as much as with ripgrep

Philosophy Differences

FindeRS philosophy:

Simple is better than complex
Explicit is better than implicit
Good enough performance for most use cases
Optimize for daily development tasks

ripgrep philosophy:

Fast is better than slow
Smart defaults (respect .gitignore)
Feature-complete grep replacement

find + grep philosophy:

Maximum flexibility
Composability with Unix tools
POSIX compliance

Migration Guide

From find + grep

# Before
find . -name "*.rs" -exec grep -H "TODO" {} \;

# After
finder -f ".rs" -s "TODO"

From ripgrep

# Before
rg "TODO" --type rust

# After
finder -f ".rs" -s "TODO"

Note: FindeRS doesn’t automatically detect file types, you need to specify the extension.

Next Steps

Check Performance for optimization tips
Review Common Use Cases for practical examples
See CLI Reference for all available options

Performance

Understanding FindeRS performance characteristics and optimization strategies.

Performance Goals

FindeRS is designed to be fast enough for daily development tasks, not the absolute fastest tool. The goal is:

“Fast enough that you never notice, simple enough that you always remember”

Benchmark Results

Comparison with Other Tools

Latest benchmark results: View detailed benchmarks →

The benchmark suite compares FindeRS against find+grep and ripgrep across different repository sizes (small, medium, large) and search patterns (common, rare). Results are updated automatically on every release.

Key observations:

FindeRS is significantly faster than find+grep
FindeRS is comparable to ripgrep for small to medium projects
For very large codebases (100k+ files), ripgrep pulls ahead
For typical development work (< 10k files), the difference is negligible

Real-world Performance

Typical project sizes:

Small project (React app): ~500 files → 5ms
Medium project (Rust service): ~2,000 files → 12ms
Large project (monorepo): ~20,000 files → 95ms

All well within “feels instant” territory.

Performance Characteristics

What Makes FindeRS Fast

Streaming Architecture
- Files processed as found, not loaded into memory
- Memory usage stays constant regardless of result count
- Starts outputting matches immediately
Efficient File Walking
- Uses platform-optimized directory traversal
- Minimal allocations during directory scanning
- Skips unreadable files quickly
Smart Pattern Matching
- Literal string search uses optimized Boyer-Moore variant
- Regex compilation happens once, not per file
- UTF-8 validation only when needed

What Limits Performance

Single-threaded by design
- Simpler implementation, easier to reason about
- Sufficient for typical use cases
- Parallelization planned for future versions
No .gitignore handling
- Searches all files, including build artifacts
- Can be slower on projects with large node_modules/ or target/
- Solution: Use shell patterns to limit search scope
No directory caching
- Each search walks the directory tree fresh
- Good: Always up-to-date results
- Bad: Repeated searches don’t get faster

Optimization Strategies

Limit Search Scope

Instead of searching the entire project:

# ❌ Slow: searches everything including node_modules
finder -s "pattern"

# ✅ Fast: search only source directory
finder src/ -s "pattern"

# ✅ Fast: target specific file types in directory
finder src/ -f ".rs" -s "pattern"

Use Specific File Patterns

# ❌ Slower: search all files then filter
finder -s "TODO" | grep ".rs:"

# ✅ Faster: filter files during search
finder -f ".rs" -s "TODO"

Choose the Right Output Mode

# If you only need file paths:
finder -s "pattern" -l  # Faster, stops after first match per file

# If you need match counts:
finder -s "pattern" -c  # Faster, no need to format output

# If you need full context:
finder -s "pattern"     # Slower, formats each match

Optimize Regex Patterns

# ❌ Slow: complex regex
finder -r ".*TODO.*|.*FIXME.*"

# ✅ Fast: simpler alternative
finder -r "TODO|FIXME"

# ✅ Faster: literal search if no regex needed
finder -s "TODO"

Exclude Large Directories

# Manually exclude directories
finder src/ tests/ -s "pattern"

# Or use find to pre-filter
find . -type f -not -path "*/node_modules/*" -not -path "*/target/*" | \
  xargs finder -s "pattern"

Memory Usage

FindeRS has minimal memory footprint:

Base memory: ~2-3 MB (Rust binary overhead)
Per-file overhead: negligible (streaming processing)
Large results: constant memory (prints as it finds)

Example: Searching 100k files with 10k matches uses ~3MB RAM.

Disk I/O Patterns

FindeRS is I/O bound, not CPU bound:

Directory traversal is sequential (OS-optimized)
File reads are buffered (8KB chunks)
No unnecessary seeks or multiple passes

Tip: Performance on SSD vs HDD:

SSD: ~10x faster due to random access patterns
HDD: limited by seek time when walking large directory trees

Scaling Considerations

When FindeRS is Fast Enough

Projects under 50k files
Local development (SSD)
Ad-hoc searches (not in tight loops)
Interactive use

When to Consider Alternatives

Monorepos with 100k+ files → use ripgrep
Repeated searches (CI/CD) → cache file lists
Network filesystems → use local checkouts
Need .gitignore filtering → use ripgrep

Future Performance Improvements

Planned optimizations:

Parallel file processing
- Process multiple files concurrently
- Target: 3-5x speedup on multi-core systems
- Status: Planned for v4.0.0
Directory ignore patterns
- Skip common build directories automatically
- Target: 2x speedup on typical projects
- Status: Under consideration
Incremental search results
- Streaming JSON output
- Target: Better experience with large result sets
- Status: Planned for v4.1.0

Benchmarking Your Use Case

To benchmark on your own projects:

# Simple timing
time finder -s "pattern" > /dev/null

# Compare with ripgrep
time rg "pattern" > /dev/null

# Test different approaches
time finder src/ -s "pattern" > /dev/null  # Limited scope
time finder -f ".rs" -s "pattern" > /dev/null  # File filtering

Performance Profiling

For detailed performance analysis:

# Build with profiling
cargo build --release --features profiling

# Run with profiling (requires Instruments on macOS or perf on Linux)
cargo instruments -t time --release -- -s "pattern"

Next Steps

Review Comparison with other tools
Check Common Use Cases for efficient patterns
See Advanced Patterns for optimization techniques

Troubleshooting

Common issues and their solutions.

Installation Issues

“command not found: finder”

Problem: Shell can’t find the finder binary.

Solution: Add the binary location to your PATH:

# Check where finder is installed
which finder

# If not found, add to PATH (in ~/.bashrc or ~/.zshrc)
export PATH="$PATH:/usr/local/bin"

# Or for cargo install
export PATH="$PATH:$HOME/.cargo/bin"

# Reload shell configuration
source ~/.bashrc  # or source ~/.zshrc

Permission Denied

Problem: Binary is not executable.

Solution: Make it executable:

chmod +x /usr/local/bin/finder

macOS “cannot be opened because the developer cannot be verified”

Problem: macOS Gatekeeper blocks unsigned binaries.

Solution:

# Remove quarantine attribute
xattr -d com.apple.quarantine /usr/local/bin/finder

# Or allow in System Preferences:
# System Preferences → Security & Privacy → General → Allow anyway

Search Issues

No Results When Expected

Check 1: Verify the pattern

# Test with simple, known pattern first
finder -s "README"

# Check case sensitivity
finder -s "pattern" -i

Check 2: Verify file filtering

# Remove file filter to search all files
finder -s "pattern"  # Without -f flag

# Check if files exist
finder -f ".rs" -l

Check 3: Verify search location

# Explicitly specify directory
finder /path/to/project -s "pattern"

# Check current directory
pwd

Too Many Results

Limit scope:

# Search specific directory
finder src/ -s "pattern"

# Add file filter
finder -f ".rs" -s "pattern"

# Use more specific pattern
finder -r "^TODO:" -s "pattern"  # Line must start with TODO:

Regex Not Working

Problem: Pattern not matching as expected.

Common issues:

# ❌ Wrong: shell interprets special characters
finder -r *.rs

# ✅ Correct: quote the pattern
finder -r ".*\.rs$"

# ❌ Wrong: mixing regex and literal search
finder -s -r "pattern"  # Can't use both

# ✅ Correct: choose one
finder -r "pattern"  # Regex
finder -s "pattern"  # Literal

Test your regex:

# Use a simple pattern first
finder -r "test"

# Add complexity gradually
finder -r "test.*function"
finder -r "test.*function.*\("

Files Not Being Searched

Check permissions:

# Run with verbose flag
finder -s "pattern" -v

# This will show files that couldn't be read

Common causes:

File is binary (only searches text files)
Permission denied
Symbolic link to non-existent file

Output Issues

No Colored Output

Check 1: Verify terminal support

# Force colors on
finder -s "pattern" --colour

Check 2: Check environment variables

# Check if colors are disabled
echo $NO_COLOR  # Should be empty

# Check CLICOLOR settings
echo $CLICOLOR
echo $CLICOLOR_FORCE

Solution:

# Enable colors
unset NO_COLOR

# Or force colors
finder -s "pattern" --colour

Colored Output in Pipes/Files

Problem: Colors appear as escape codes when piping or redirecting.

Solution:

# Remove colors for pipes
finder -s "pattern" --no-colour > output.txt

# Or keep colors for less
finder -s "pattern" --colour | less -R

JSON Output Invalid

Problem: JSON output is malformed.

Check:

# Validate JSON
finder -s "pattern" --json | jq .

# If jq fails, check for:
# - Binary files in output (shouldn't happen, but check with -v)
# - Special characters in filenames

Solution:

# Use verbose mode to identify problematic files
finder -s "pattern" --json -v

Performance Issues

Very Slow Search

Check 1: Are you searching too many files?

# Count files being searched
find . -type f | wc -l

# Limit scope
finder src/ -s "pattern"  # Instead of finder -s "pattern"

Check 2: Is it a network drive?

# Check mount points
df -h .

# Copy to local disk if on network drive

Check 3: Large binary files?

# Find large files
find . -type f -size +10M

# Exclude them from search
finder src/ -s "pattern"  # Instead of root directory

High Memory Usage

This shouldn’t happen - FindeRS uses streaming processing.

If you’re seeing high memory usage:

Check if you’re collecting all output in memory:

# ❌ Bad: stores all results
results=$(finder -s "pattern")

# ✅ Good: process as stream
finder -s "pattern" | while read line; do
  process "$line"
done

Report as a bug with reproduction steps

Error Messages

“Permission denied”

Cause: Can’t read file or directory.

Solution: Usually safe to ignore - these files are skipped. Use -v to see which files:

finder -s "pattern" -v

“Invalid regex pattern”

Cause: Malformed regular expression.

Solution:

# Check regex syntax
finder -r "valid.*pattern"

# Escape special characters
finder -r "test\.rs"  # Literal dot
finder -r "\\$"       # Literal dollar sign

# Test pattern separately
echo "test string" | grep -E "your.*pattern"

“No such file or directory”

Cause: Specified path doesn’t exist.

Solution:

# Check path exists
ls /path/to/search

# Use relative or absolute path
finder ./src -s "pattern"
finder /absolute/path -s "pattern"

Integration Issues

Not Working in Shell Scripts

Problem: Works in terminal but not in scripts.

Common causes:

# ❌ PATH not set in script
#!/bin/bash
finder -s "pattern"  # May not find finder

# ✅ Use full path or set PATH
#!/bin/bash
export PATH="$PATH:/usr/local/bin"
finder -s "pattern"

# Or use full path
/usr/local/bin/finder -s "pattern"

Not Working in Cron

Problem: Works manually but not in cron.

Solution: Cron has minimal environment:

# In crontab, set PATH
PATH=/usr/local/bin:/usr/bin:/bin

# Or use full path in command
0 9 * * * /usr/local/bin/finder /path/to/project -s "pattern"

Not Working in Git Hooks

Problem: Hooks can’t find finder.

Solution: Same as scripts - set PATH or use full path:

#!/bin/bash
# .git/hooks/pre-commit

PATH="/usr/local/bin:$PATH"
finder -s "NOCOMMIT" || exit 1

Platform-Specific Issues

Windows: Line Endings

Problem: Not finding patterns at line ends on Windows files.

Cause: Windows uses CRLF (\r\n), searches may not account for \r.

Solution:

# Convert line endings
find . -type f -name "*.txt" -exec dos2unix {} \;

# Or search for pattern with optional \r
finder -r "pattern\r?$"

macOS: Spotlight Interference

Problem: Slow searches immediately after updating files.

Cause: Spotlight indexing in background.

Solution: Wait a moment, or:

# Exclude from Spotlight temporarily
sudo mdutil -i off /path/to/project
finder -s "pattern"
sudo mdutil -i on /path/to/project

Getting Help

Gathering Debug Information

When reporting issues, include:

# Version
finder --version

# System info
uname -a

# Command that failed (with -v flag)
finder -s "pattern" -v

# Environment
env | grep -E "(COLOR|PATH)"

Where to Get Help

GitHub Issues: https://github.com/ydkadri/finders/issues
Documentation: https://ydkadri.github.io/finders
Email: youcef.kadri@example.com

Before Reporting a Bug

Check this troubleshooting guide
Try with latest version (finder --version)
Test with minimal example
Include reproduction steps

Next Steps

Review Common Use Cases for usage patterns
Check CLI Reference for all options
See Performance for optimization tips

Contributing

Thanks for your interest in contributing to FindeRS! This is a personal project that grew into my daily command-line companion, and I’m happy to have others involved.

Getting Started

FindeRS is written in Rust. You’ll need:

Rust 1.70 or later (rustup update)
Git
A GitHub account (for pull requests)

Clone and build:

git clone https://github.com/ydkadri/finders.git
cd finders
cargo build
cargo test

Areas for Contribution

I’m particularly interested in:

Bug fixes - If something doesn’t work as documented, please fix it!
Documentation - Improvements to examples, clarifications, typo fixes
Performance - Benchmarks, profiling, optimization ideas
Testing - More test cases, especially edge cases
Examples - Real-world usage patterns and integration examples

Before You Start

For anything beyond typos and documentation:

Open an issue first to discuss the change
Wait for feedback before investing significant time
Keep changes focused and atomic

This helps ensure your effort aligns with the project direction.

Development Workflow

Making Changes

Fork the repository
Create a feature branch (git checkout -b fix/your-fix)
Make your changes
Write or update tests
Run the checks (see below)
Commit with clear messages
Push and open a pull request

Quality Checks

Before submitting:

# Format code
cargo fmt

# Lint
cargo clippy -- -D warnings

# Test
cargo test

# Benchmarks (if you changed performance-sensitive code)
cargo bench

All checks must pass before your PR can be merged.

Writing Tests

Add unit tests in the same file as the code
Add integration tests in tests/ for end-to-end scenarios
Test both happy paths and error cases

Example:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_your_feature() {
        // Arrange
        let input = setup_test_data();
        
        // Act
        let result = your_function(input);
        
        // Assert
        assert_eq!(result, expected);
    }
}
}

Commit Messages

Keep them clear and descriptive:

Fix regex escaping in file patterns

Filenames with dots were incorrectly treated as regex
metacharacters. Now properly escape special characters
before compiling regex patterns.

Fixes #42