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.

Table of Contents

Gem Usage:

• Installation
• Programmatic API
• CLI

Community Resources:

• Getting Help and Contributing
• License
• Code of Conduct

Installation

Install the gem:

gem install grepfruit

Programmatic API

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,
  relative_paths: false
)

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

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

Match paths are absolute by default. With relative_paths: true, they are relative to the search directory, or just the file name when a single file is searched. search.path is always absolute.

All keyword arguments correspond to their CLI flag counterparts.

CLI

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.

Command Line Options

Option	Description
-r, --regex REGEX	Regex pattern to search for (required)
-e, --exclude x,y,z	Comma-separated list of files, directories, or lines to exclude: names, wildcards, paths relative to the search directory, or file:line
-i, --include x,y,z	Comma-separated list of files to include: names, wildcards, or paths relative to the search directory
-t, --truncate N	Truncate search result output to N characters
-j, --jobs N	Number of parallel workers (default: number of CPU cores)
-c, --count	Show only match counts, not match details
-p, --relative-paths	Show match paths relative to the search directory
--search-hidden	Include hidden files and directories in search
--json	Output results in JSON format

Usage Examples

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/",
    "path": "/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": "/path/to/search/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'

Relative Paths

Match paths are absolute by default. Show them relative to the search directory instead:

grepfruit search -r 'TODO' --relative-paths dev/my_app
grepfruit search -r 'TODO' -p dev/my_app/README.md  # Shows just the file name

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

Exit Status

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)

Getting Help and Contributing

Getting Help

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

• Usage questions
• Implementation guidance
• Open-ended ideas or suggestions

Issues

Issues track bugs, planned features, and other work. When reporting a bug, please include:

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

Contributing Code

Any open issue is free to pick up or discuss. Check the project board or issues tab.

Before contributing, please read the contributing guidelines.

License

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

Code of Conduct

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