ripgo

README

ripgo

Ripgrep-compatible search engine designed library-first in idiomatic Go. Each package is independently importable with zero CLI dependencies.

Quick Start

High-Level API (ripgo.Search)

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/nijaru/ripgo"
)

func main() {
	ctx := context.Background()

	for res, err := range ripgo.Search(ctx, `func \w+`, []string{"."},
		ripgo.WithTypes([]string{"go"}),
		ripgo.WithSmartCase(true),
	) {
		if err != nil {
			log.Printf("error: %v", err)
			continue
		}
		for _, m := range res.Matches {
			fmt.Printf("%s:%d:%d: %s\n", res.Path, m.Line, m.Column, m.LineBytes)
		}
	}
}

Low-Level Package Composition

import (
	"github.com/nijaru/ripgo/pattern"
	"github.com/nijaru/ripgo/printer"
	"github.com/nijaru/ripgo/search"
)

m, _ := pattern.New(pattern.Config{Pattern: "TODO", SmartCase: true})
s := search.NewSearcher(nil, search.Config{MaxCount: 100, Before: 2, After: 2}, m)
result, _ := s.SearchPath("file.go", nil)

p := printer.NewTextPrinter(printer.TextConfig{LineNumber: true})
p.PrintResult(result)

Packages

Package	Purpose	Key Types
ripgo	High-level orchestrator & iter.Seq2 streaming API	Search(), Option
pattern	Literal fast-path, regex RE2, and PCRE2 matching	Matcher, Config, New()
search	File scanning, mmap, line context, replace (-r), only-matching (-o)	Searcher, Result, Match, Entry
walk	Depth-first concurrent traversal, lazy stats, binary detection	Walker, Entry
ignore	Gitignore rules, parent cascading, negation, globstar, type filters	Engine, IgnoreRule, IgnoreSet
printer	Text (colors/headings/truncation), JSON, count, and file printers	Printer, TextPrinter, JSONPrinter
stats	Atomic match and file counters	Stats

CLI

A thin CLI harness is included at cmd/ripgo for benchmarking and testing:

go install github.com/nijaru/ripgo/cmd/ripgo@latest

ripgo "TODO" .
ripgo -n -C 3 -t go "func main" .
ripgo -o "\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b" .

Performance

Benchmarked against rg (ripgrep) across 15,000 Go source files in the Kubernetes 1.31 repository:

Tool	Mean Time
rg (ripgrep)	593 ms
ripgo	661 ms

License

MIT

Documentation

Overview

Package ripgo provides a high-level API for searching files.

It orchestrates traversal (walk), filtering (ignore), and pattern matching (pattern) into a simple, unified interface for library consumers.

Basic Usage

The primary entry point is the Search function, which returns an iterator of results:

ctx := context.Background()
results := ripgo.Search(ctx, "TODO", []string{"."}, ripgo.WithIgnoreCase(true))

for res, err := range results {
    if err != nil {
        fmt.Fprintf(os.Stderr, "Error: %v\n", err)
        continue
    }
    fmt.Printf("%s: %d matches\n", res.Path, len(res.Matches))
}

Functional Options

Search can be configured using functional options:

• WithMultiline(true): Enable multiline matching across line boundaries.
• WithWordRegexp(true): Match whole words only.
• WithContext(before, after): Include context lines around matches.
• WithReplace("template"): Perform string replacement using capture groups.
• WithPcre2(true): Use the PCRE2 regex engine instead of Go's default.

Filesystem Abstraction

ripgo works with any io/fs.FS implementation via the WithFS option. This allows searching in-memory files, zip archives, or remote storage:

myFS := fstest.MapFS{...}
results := ripgo.Search(ctx, "pattern", []string{"."}, ripgo.WithFS(myFS))

Architecture

The project is divided into several focused packages:

• github.com/nijaru/ripgo/search: File scanning and match reporting.
• github.com/nijaru/ripgo/pattern: Multi-engine pattern matching (Literal, Regex, PCRE2).
• github.com/nijaru/ripgo/walk: Parallel directory traversal.
• github.com/nijaru/ripgo/ignore: Gitignore-compatible filtering logic.

Package ripgo provides a high-level API for searching files.

It orchestrates the walk, ignore, pattern, and search packages into a simple, unified interface for library consumers.

Index

• func Search(ctx context.Context, patternStr string, paths []string, opts ...Option) iter.Seq2[search.Result, error]
• type Config
  • func DefaultConfig(pat string) Config
• type Option
  • func WithContext(before, after int) Option
  • func WithFS(fsys fs.FS) Option
  • func WithFixedStrings(v bool) Option
  • func WithFollowSymlinks(v bool) Option
  • func WithGlobExcludes(globs ...string) Option
  • func WithGlobIncludes(globs ...string) Option
  • func WithHidden(v bool) Option
  • func WithIgnoreCase(v bool) Option
  • func WithMatcher(m pattern.Matcher) Option
  • func WithMaxCount(n int) Option
  • func WithMaxFileSize(n int64) Option
  • func WithMultiline(v bool) Option
  • func WithNoIgnore(v bool) Option
  • func WithOnlyMatching(v bool) Option
  • func WithPcre2(v bool) Option
  • func WithReplace(v string) Option
  • func WithThreads(n int) Option
  • func WithTypes(types []string) Option
  • func WithTypesNot(typesNot []string) Option
  • func WithWordRegexp(v bool) Option

Functions

func Search

func Search(ctx context.Context, patternStr string, paths []string, opts ...Option) iter.Seq2[search.Result, error]

Search performs a complete search using the provided configuration and paths. It returns an iterator of (Result, error). The error is non-nil if a file-level error was encountered (e.g. Permission Denied).

Types

type Config

type Config struct {
	Pattern pattern.Config
	Search  search.Config
	Walk    walk.Config
	Ignore  ignore.Config
	FS      fs.FS
	Matcher pattern.Matcher
}

Config represents the complete search configuration.

func DefaultConfig

func DefaultConfig(pat string) Config

DefaultConfig returns a configuration with sensible defaults.

type Option

type Option func(*Config)

Option is a functional option for configuring the search.

func WithContext

func WithContext(before, after int) Option

func WithFS

func WithFS(fsys fs.FS) Option

func WithFixedStrings

func WithFixedStrings(v bool) Option

func WithFollowSymlinks

func WithFollowSymlinks(v bool) Option

func WithGlobExcludes

func WithGlobExcludes(globs ...string) Option

func WithGlobIncludes

func WithGlobIncludes(globs ...string) Option

func WithHidden

func WithHidden(v bool) Option

func WithIgnoreCase

func WithIgnoreCase(v bool) Option

func WithMatcher

func WithMatcher(m pattern.Matcher) Option

func WithMaxCount

func WithMaxCount(n int) Option

func WithMaxFileSize

func WithMaxFileSize(n int64) Option

func WithMultiline

func WithMultiline(v bool) Option

func WithNoIgnore

func WithNoIgnore(v bool) Option

func WithOnlyMatching

func WithOnlyMatching(v bool) Option

func WithPcre2

func WithPcre2(v bool) Option

func WithReplace

func WithReplace(v string) Option

func WithThreads

func WithThreads(n int) Option

func WithTypes

func WithTypes(types []string) Option

func WithTypesNot

func WithTypesNot(typesNot []string) Option

func WithWordRegexp

func WithWordRegexp(v bool) Option