ripgo

package module

v0.0.0-...-927ff6d Latest Latest Go to latest Published: Aug 16, 2026 License: MIT Imports: 15 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/nijaru/ripgo

Links

Open Source Insights

README ¶

ripgo

Ripgrep-compatible content search and fd-like path finding, 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)
		}
	}
}

High-Level API (`ripgo.Find`)

Use the finder for fd-style name and metadata queries. It streams metadata-only results and does not read file contents:

import (
	"context"
	"fmt"
	"log"

	"github.com/nijaru/ripgo"
	"github.com/nijaru/ripgo/find"
)

func main() {
	ctx := context.Background()
	for result, err := range ripgo.Find(ctx, `\.go$`, []string{"."},
		ripgo.WithFindType(find.TypeFile),
		ripgo.WithFindExtension("go"),
	) {
		if err != nil {
			log.Printf("error: %v", err)
			continue
		}
		fmt.Println(result.Path)
	}
}

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 search and finder orchestration with `iter.Seq2`	`Search()`, `Find()`, `Option`, `FindOption`
`find`	Filename, path, and metadata matching for finder mode	`Matcher`, `Filter`, `Result`
`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`
`fsref`	Capability-backed file access with mmap/read fallback	`Ref`, `Root`
`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 is included at cmd/ripgo:

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" .

# Find paths by name, without reading file contents
ripgo find --glob '*.go' --type f .
ripgo find --type d --max-depth 2 .

ripgo find supports regex, glob, fixed-string, type, extension, size, depth, ignore, symlink, and path-output filters. Finder actions are explicit and shell-free: --exec 'command {}' runs once per match, while --exec-batch 'command {}' expands a bounded batch. --delete requires --type f or --type l, removes only matched directory entries (never follows a symlink), and supports --dry-run. Actions stop on the first failure; earlier effects are not rolled back. Actions require {} and do not support --sort or --print0 (except delete previews). See ripgo find --help for the current surface.

Finder benchmark

Run the reproducible local comparison with fd:

scripts/bench_find.sh

The script creates a disposable fixture, builds a trimmed ripgo binary, and runs paired path-listing, matching, depth, ignore, and symlink workloads with Hyperfine. It records tool versions, fixture shape, warmups, measured runs, and Markdown results in tmp/bench_find.md. Results are machine-specific evidence, not a general performance claim.

License

MIT

Documentation ¶

Overview ¶

Package ripgo provides high-level APIs for searching file contents and finding filesystem paths.

It orchestrates traversal (walk), filtering (ignore), and matching (pattern and find) into simple streaming interfaces 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))
}

Finding Paths ¶

Find matches names and metadata without reading file contents:

for result, err := range ripgo.Find(ctx, `\.go$`, []string{"."},
	ripgo.WithFindType(find.TypeFile)) {
	if err != nil {
		continue
	}
	fmt.Println(result.Path)
}

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/find: Filename, path, and metadata matching.
github.com/nijaru/ripgo/pattern: Multi-engine pattern matching (Literal, Regex, PCRE2).
github.com/nijaru/ripgo/walk: Parallel directory traversal.
github.com/nijaru/ripgo/fsref: Capability-backed file access.
github.com/nijaru/ripgo/ignore: Gitignore-compatible filtering logic.

Package ripgo provides high-level APIs for searching file contents and finding filesystem paths.

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

Index ¶

func DefaultFindConfig(pattern string) findpkg.Config
func Find(ctx context.Context, pattern string, paths []string, opts ...FindOption) iter.Seq2[findpkg.Result, error]
func Search(ctx context.Context, patternStr string, paths []string, opts ...Option) iter.Seq2[search.Result, error]
type Config
- func DefaultConfig(pat string) Config
type FindOption
type Option

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

func DefaultFindConfig ¶

func DefaultFindConfig(pattern string) findpkg.Config

DefaultFindConfig returns a finder configuration with pattern matching enabled and the shared walker's zero-value traversal defaults.

func Find ¶

func Find(ctx context.Context, pattern string, paths []string, opts ...FindOption) iter.Seq2[findpkg.Result, error]

Find streams matching paths from the supplied roots without reading file contents. It returns an iterator of (Result, error). A missing path or traversal failure is yielded as an error; the iterator stops when the caller stops yielding.

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 FindOption ¶

type FindOption func(*findpkg.Config)

FindOption configures Find.

func WithFindExtension ¶

func WithFindExtension(extension string) FindOption

WithFindExtension adds an extension filter. Repeated values are ORed.

func WithFindExtensions ¶

func WithFindExtensions(extensions ...string) FindOption

WithFindExtensions adds extension filters. Repeated values are ORed.

func WithFindFS ¶

func WithFindFS(fsys fs.FS) FindOption

WithFindFS selects the filesystem used by Find.

func WithFindFixedStrings ¶

func WithFindFixedStrings(v bool) FindOption

WithFindFixedStrings enables literal substring matching.

func WithFindFollowSymlinks ¶

func WithFindFollowSymlinks(v bool) FindOption

WithFindFollowSymlinks enables followed directory symlinks.

func WithFindFullPath ¶

func WithFindFullPath(v bool) FindOption

WithFindFullPath matches normalized paths relative to each search root.

func WithFindGlob ¶

func WithFindGlob(v bool) FindOption

WithFindGlob enables glob matching.

func WithFindGlobExcludes ¶

func WithFindGlobExcludes(globs ...string) FindOption

WithFindGlobExcludes excludes matching paths from finder traversal.

func WithFindHidden ¶

func WithFindHidden(v bool) FindOption

WithFindHidden includes hidden paths.

func WithFindIgnoreCase ¶

func WithFindIgnoreCase(v bool) FindOption

WithFindIgnoreCase enables case-insensitive matching and extension filters.

func WithFindMaxDepth ¶

func WithFindMaxDepth(depth int) FindOption

WithFindMaxDepth sets the inclusive maximum root-relative depth.

func WithFindMaxSize ¶

func WithFindMaxSize(size int64) FindOption

WithFindMaxSize sets the inclusive maximum metadata size.

func WithFindMetadata ¶

func WithFindMetadata(v bool) FindOption

WithFindMetadata controls whether finder results resolve file metadata. Metadata is enabled by default; disabling it leaves Result.Info nil and cannot be combined with size filters.

func WithFindMinDepth ¶

func WithFindMinDepth(depth int) FindOption

WithFindMinDepth sets the inclusive minimum root-relative depth.

func WithFindMinSize ¶

func WithFindMinSize(size int64) FindOption

WithFindMinSize sets the inclusive minimum metadata size.

func WithFindNoIgnore ¶

func WithFindNoIgnore(v bool) FindOption

WithFindNoIgnore disables ignore-file loading.

func WithFindThreads ¶

func WithFindThreads(n int) FindOption

WithFindThreads sets the finder traversal worker count.

func WithFindType ¶

func WithFindType(typ findpkg.Type) FindOption

WithFindType adds a result type filter. Repeated values are ORed.

func WithFindTypes ¶

func WithFindTypes(types ...findpkg.Type) FindOption

WithFindTypes adds result type filters. Repeated values are ORed.

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

Source Files ¶

View all Source files

Directories ¶

Path	Synopsis
cmd
ripgo command
find Package find provides filename and path matching for finder mode.	Package find provides filename and path matching for finder mode.
fsref Package fsref defines capability-backed file references used by search and traversal.	Package fsref defines capability-backed file references used by search and traversal.
ignore Package ignore implements gitignore-compatible file filtering.	Package ignore implements gitignore-compatible file filtering.
internal
action Package action implements the private, opt-in side effects of finder mode.	Package action implements the private, opt-in side effects of finder mode.
aho Package aho implements a minimal Aho-Corasick automaton for multi-literal pre-filtering.	Package aho implements a minimal Aho-Corasick automaton for multi-literal pre-filtering.
cli
config
osfs Package osfs provides an fs.FS implementation for the local OS filesystem.	Package osfs provides an fs.FS implementation for the local OS filesystem.
sys
pattern
printer Package printer implements various output formats for search results.	Package printer implements various output formats for search results.
search
stats Package stats provides search statistics tracking.	Package stats provides search statistics tracking.
walk Package walk implements parallel directory traversal.	Package walk implements parallel directory traversal.

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

README ¶

ripgo

Quick Start

High-Level API (ripgo.Search)

High-Level API (ripgo.Find)

Low-Level Package Composition

Packages

CLI

Finder benchmark

License

Documentation ¶

Overview ¶

Basic Usage ¶

Finding Paths ¶

Functional Options ¶

Filesystem Abstraction ¶

Architecture ¶

Index ¶

Constants ¶

Variables ¶

Functions ¶

func DefaultFindConfig ¶

func Find ¶

func Search ¶

Types ¶

type Config ¶

func DefaultConfig ¶

type FindOption ¶

func WithFindExtension ¶

func WithFindExtensions ¶

func WithFindFS ¶

func WithFindFixedStrings ¶

func WithFindFollowSymlinks ¶

func WithFindFullPath ¶

func WithFindGlob ¶

func WithFindGlobExcludes ¶

func WithFindHidden ¶

func WithFindIgnoreCase ¶

func WithFindMaxDepth ¶

func WithFindMaxSize ¶

func WithFindMetadata ¶

func WithFindMinDepth ¶

func WithFindMinSize ¶

func WithFindNoIgnore ¶

func WithFindThreads ¶

func WithFindType ¶

func WithFindTypes ¶

type Option ¶

func WithContext ¶

func WithFS ¶

func WithFixedStrings ¶

func WithFollowSymlinks ¶

func WithGlobExcludes ¶

func WithGlobIncludes ¶

func WithHidden ¶

func WithIgnoreCase ¶

func WithMatcher ¶

func WithMaxCount ¶

func WithMaxFileSize ¶

func WithMultiline ¶

func WithNoIgnore ¶

func WithOnlyMatching ¶

func WithPcre2 ¶

func WithReplace ¶

func WithThreads ¶

func WithTypes ¶

func WithTypesNot ¶

func WithWordRegexp ¶

Source Files ¶

Directories ¶

High-Level API (`ripgo.Search`)

High-Level API (`ripgo.Find`)