ripgo

package module
v0.0.0-...-7447bd4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 16, 2026 License: MIT Imports: 15 Imported by: 0

README

ripgo

Ripgrep-compatible content search and fd-like path finding in Go. Designed as importable packages with zero CLI dependencies, backed by a single static binary.

Quick Start

Content Search (ripgo.Search)

Stream matches using standard range iterators:

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)
		}
	}
}
Path Finding (ripgo.Find)

Match paths and filter by metadata without reading file content:

package main

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 individual packages directly for fine-grained control:

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("main.go", nil)

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

Packages

Package Purpose Key Exports
ripgo Root iterators (iter.Seq2) for search and find orchestration Search(), Find(), Option, FindOption
find Filename, path, glob, regex, and metadata matching Matcher, Filter, Result, Config
pattern Literal fast-paths, RE2 regex, PCRE2, zero-allocation line matching Matcher, LocationMatcher, New()
search Line scanning, context lines, replacement, text encodings, mmap Searcher, Result, Match, DecodeData
walk Concurrent directory traversal, depth limits, binary detection Walker, Entry, Config
fsref Capability-based file descriptors with Unix mmap and read fallback Ref, Root
ignore Gitignore rules, trie hierarchy, negation, globstar, fast-path checks Engine, IgnoreRule, IgnoreSet
printer Buffered text (ANSI colors/headings), JSON, count, and file printers Printer, TextPrinter, JSONPrinter, PathPrinter
stats Atomic match and file counters Stats

CLI

A single static binary providing both ripgrep and fd workflows:

go install github.com/nijaru/ripgo/cmd/ripgo@latest
Grep Usage (ripgo [FLAGS] PATTERN [PATH...])
ripgo "TODO" .
ripgo -n -C 3 -t go "func main" .
ripgo -i "goroutine" .
ripgo -E utf-16le "pattern" .
ripgo -o "\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b" .
Find Usage (ripgo find [FLAGS] [PATTERN] [PATH...])
ripgo find --glob '*.go' --type f .
ripgo find --type d --max-depth 2 .
ripgo find --size +10M .
ripgo find --exec 'wc -l {}' .

ripgo find supports regex, glob, fixed-string, type, extension, size, depth, ignore, symlink, and path-output formatting. Actions are shell-free: --exec 'command {}' executes once per match, while --exec-batch 'command {}' passes batched paths. --delete removes matched files or symlinks without following targets, and supports --dry-run.

Benchmarks

Reproducible benchmarks against ripgrep and fd using hyperfine:

# Content search benchmark vs ripgrep (rg)
scripts/bench.sh

# Path traversal benchmark vs fd
scripts/bench_find.sh
  • Content Search: Within ~2–5% of ripgrep on 10,000+ file trees, with faster process startup on small repositories.
  • Path Traversal: Within ~1.6–1.8× of fd with cycle-safe symlink resolution and .gitignore evaluation.

License

MIT

Documentation

Overview

Package ripgo provides streaming APIs for searching file contents and finding filesystem paths.

It integrates traversal, ignore-rule filtering, and pattern matching into range-over-func iterators over any io/fs.FS filesystem.

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

Examples

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.

Example 
package main

import (
	"context"
	"fmt"

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

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

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

Output:
doc.go

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(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 WithEncoding 

func WithEncoding(enc string) Option

WithEncoding sets the text encoding for content search (e.g. "auto", "utf-16le", "latin1", "none").

func WithFS 

func WithFS(fsys fs.FS) Option

func WithFixedStrings 

func WithFixedStrings(v bool) Option
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 WithSmartCase 

func WithSmartCase(v bool) Option

WithSmartCase enables case-insensitive matching unless uppercase characters are present.

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
Package find provides filename and path matching for finder mode.
 Package find provides filename and path matching for finder mode.
Package fsref defines capability-backed file references used by search and traversal.
 Package fsref defines capability-backed file references used by search and traversal.
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
Package printer implements various output formats for search results.
 Package printer implements various output formats for search results.
Package stats provides search statistics tracking.
 Package stats provides search statistics tracking.
Package walk implements parallel directory traversal.
 Package walk implements parallel directory traversal.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.