Grepfruit is a Ruby gem for searching files within a directory for specified regular expression patterns, with exclusion options and JSON-formatted or colorized output for enhanced readability. Originally designed for CI/CD pipelines to search for TODO comments in Ruby on Rails applications, Grepfruit provides more user-friendly output than the standard grep command while maintaining the flexibility for diverse search scenarios.

Key Features:

• Parallel search using Ractors
• JSON output format for programmatic integration
• Colorized output for improved readability
• CI/CD pipeline friendly exit codes

Gem Usage:

• Installation
• Basic Usage
• Command Line Options
• Usage Examples
• Exit Status

Community Resources:

• Getting Help and Contributing
• License
• Code of Conduct

Install the gem:

gem install grepfruit

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.

Search for TODO comments in the current directory:

grepfruit search -r 'TODO'

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

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

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

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

Exclude specific lines from search results:

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

Limit output length for cleaner results:

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

Search hidden files and directories:

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

Get structured JSON output:

grepfruit search -r 'TODO' --json

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

{
  "search": {
    "pattern": "/TODO/",
    "directory": "/path/to/search",
    "exclusions": ["node_modules"],
    "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"
    },
    // ...
  ]
}

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 (ideal for quality gates - code is clean)
• Exit code 1: Pattern matches were found (CI should fail - issues detected)

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.