Grepfruit: Regex Search in Files

Grepfruit is a Ruby gem for regex pattern searching, offering both a programmatic API and a CI/CD-friendly CLI.

Gem Usage:

• Installation
• Programmatic API
• CLI

Community Resources:

• Getting Help and Contributing
• License
• Code of Conduct

Install the gem:

gem install grepfruit

Use Grepfruit directly in Ruby applications:

result = Grepfruit.search(
  regex: /TODO|FIXME/,
  path: "app",
  exclude: ["tmp", "vendor"],
  include: ["*.rb"],
  truncate: 80,
  search_hidden: false,
  jobs: 4,
  count: false
)

Returns a hash (when count: true, the matches key is omitted):

{
  search: {
    pattern: /TODO|FIXME/,
    directory: "/path/to/app",
    exclusions: ["tmp", "vendor"],
    inclusions: ["*.rb"]
  },
  summary: {
    files_checked: 42,
    files_with_matches: 8,
    total_matches: 23
  },
  matches: [
    { file: "models/user.rb", line: 15, content: "# TODO: add validation" },
    # ...
  ]
}

All keyword arguments correspond to their CLI flag counterparts.

Search for regex patterns within files in a specified directory:

grepfruit search [options] [PATH]

Or using shorthand s command:

grepfruit s [options] [PATH]

If no PATH is specified, Grepfruit searches the current directory.

Basic Pattern Search

Search for TODO comments in the current directory:

grepfruit search -r 'TODO'

Excluding Directories

Search for TODO patterns while excluding common build and dependency directories:

grepfruit search -r 'TODO' -e 'log,tmp,vendor,node_modules,assets'

Multiple Pattern Search Excluding Both Directories and Files

Search for both FIXME and TODO comments in a specific directory:

grepfruit search -r 'FIXME|TODO' -e 'bin,*.md,tmp/log,Gemfile.lock' dev/my_app

Line-Specific Exclusion

Exclude specific lines from search results:

grepfruit search -r 'FIXME|TODO' -e 'README.md:18'

Including Specific File Types

Search only in specific file types using patterns:

grepfruit search -r 'TODO' -i '*.rb,*.js'
grepfruit search -r 'FIXME' -i '*.py'

Output Truncation

Limit output length for cleaner results:

grepfruit search -r 'FIXME|TODO' -t 50

Including Hidden Files

Search hidden files and directories:

grepfruit search -r 'FIXME|TODO' --search-hidden

JSON Output

Get structured JSON output:

grepfruit search -r 'TODO' -e 'node_modules' -i '*.rb,*.js' --json /path/to/search

This outputs a JSON response containing search metadata, summary statistics, and detailed match information:

{
  "search": {
    "pattern": "/TODO/",
    "directory": "/path/to/search",
    "exclusions": ["node_modules"],
    "inclusions": ["*.rb", "*.js"],
    "timestamp": "2025-01-16T10:30:00+00:00"
  },
  "summary": {
    "files_checked": 42,
    "files_with_matches": 8,
    "total_matches": 23
  },
  "matches": [
    {
      "file": "src/main.js",
      "line": 15,
      "content": "// TODO: Implement error handling"
    },
    // ...
  ]
}

Count Only Mode

Show only match counts without displaying the actual matches:

grepfruit search -r 'TODO' --count
grepfruit search -r 'FIXME|TODO' -c -e 'vendor,node_modules'

Parallel Processing

Grepfruit uses ractors for true parallel processing across CPU cores. Control the number of parallel workers:

grepfruit search -r 'TODO' -j 8  # Use 8 parallel workers
grepfruit search -r 'TODO' -j 1  # Sequential processing

Grepfruit returns meaningful exit codes for CI/CD integration:

• Exit code 0: No matches found (useful for quality gates)
• Exit code 1: Pattern matches were found (indicates issues)

Have a question or need assistance? Open a discussion in our discussions section for:

• Usage questions
• Implementation guidance
• Feature suggestions

Found a bug? Please create an issue with:

• A clear description of the problem
• Steps to reproduce the issue
• Your environment details (Ruby version, OS, etc.)

Ready to contribute? You can:

• Fix bugs by submitting pull requests
• Improve documentation
• Add new features (please discuss first in our discussions section)

Before contributing, please read the contributing guidelines

The gem is available as open source under the terms of the MIT License.

Everyone interacting in the Grepfruit project is expected to follow the code of conduct.