finder

Documentation

Overview

Package finder is the core engine of go-fd. It performs a parallel, gitignore-aware filesystem walk and applies fd's filters, mirroring the behavior of the original Rust implementation. It also exposes the SDK entry points (Finder, Config, Find, FindStream).

Index

• Constants
• type Config
  • func (c *Config) IsPrinting() bool
• type DirEntry
  • func (e *DirEntry) Depth() int
  • func (e *DirEntry) Info() (os.FileInfo, error)
  • func (e *DirEntry) IsDir() bool
  • func (e *DirEntry) Path() string
  • func (e *DirEntry) StrippedPath(cfg *Config) string
  • func (e *DirEntry) Type() fs.FileMode
• type ExitCode
• type FileType
• type FileTypes
• type Finder
  • func New(cfg *Config) (*Finder, error)
  • func (f *Finder) Config() *Config
  • func (f *Finder) Find(ctx context.Context, paths []string) ([]string, error)
  • func (f *Finder) Run(ctx context.Context, paths []string) ExitCode
  • func (f *Finder) SetPatterns(patterns []*regexp.Regexp)
  • func (f *Finder) Stream(ctx context.Context, paths []string) (<-chan Result, <-chan error)
• type LsColors
  • func ParseLsColors(s string) *LsColors
• type Result

Constants

const DefaultLsColors = "" /* 535-byte string literal not displayed */

DefaultLsColors is the molokai-derived default palette used by fd when LS_COLORS is not present in the environment.

Types

type Config

type Config struct {
	// CaseSensitive controls case sensitivity of the pattern match.
	CaseSensitive bool

	// FullPathBase, when non-empty, makes patterns match against the absolute
	// path (rooted at this directory) instead of the file name only.
	FullPathBase string

	// IgnoreHidden skips dotfiles/dotdirs when true.
	IgnoreHidden bool

	// ReadFdignore respects .fdignore and .ignore files.
	ReadFdignore bool
	// ReadParentIgnore respects ignore files in parent directories.
	ReadParentIgnore bool
	// ReadVcsignore respects .gitignore files.
	ReadVcsignore bool
	// RequireGit only respects gitignore inside a git repository.
	RequireGit bool
	// ReadGlobalIgnore respects the global ignore file.
	ReadGlobalIgnore bool

	// FollowLinks traverses symlinked directories.
	FollowLinks bool
	// OneFileSystem prevents descending into other filesystems.
	OneFileSystem bool

	// NullSeparator separates results with NUL instead of newline.
	NullSeparator bool

	// MaxDepth/MinDepth limit traversal depth. nil means unbounded.
	MaxDepth *int
	MinDepth *int

	// Prune stops descending into matching directories.
	Prune bool

	// Threads is the worker count (defaults applied by the caller).
	Threads int

	// Quiet suppresses output; the search reports only whether a match exists.
	Quiet bool

	// MaxBufferTime is the duration to buffer results for sorting before
	// streaming. Zero uses the default.
	MaxBufferTime time.Duration

	// Colored enables LS_COLORS-based colorization.
	Colored  bool
	LsColors *LsColors

	// Hyperlink wraps each path in an OSC 8 terminal hyperlink.
	Hyperlink bool

	// InteractiveTerminal reports whether stdout is a TTY.
	InteractiveTerminal bool

	// FileTypes restricts results by entry kind (nil = all).
	FileTypes *FileTypes

	// Extensions restricts results to matching file extensions (nil = all).
	Extensions []string

	// Format renders results with a template (nil = plain path).
	Format *format.Template

	// Command runs a command per result / batch (nil = print).
	Command *exec.CommandSet
	// BatchSize bounds arguments per batch command (0 = unlimited).
	BatchSize int

	// ExcludePatterns are gitignore-style globs that exclude entries.
	ExcludePatterns []string

	// IgnoreFiles are custom ignore files in gitignore format.
	IgnoreFiles []string

	// SizeConstraints restrict file sizes.
	SizeConstraints []filter.SizeFilter
	// TimeConstraints restrict modification times.
	TimeConstraints []filter.TimeFilter
	// OwnerConstraint restricts ownership (unix only). nil = no constraint.
	OwnerConstraint *filter.OwnerFilter

	// ShowFilesystemErrors prints traversal errors to stderr.
	ShowFilesystemErrors bool

	// PathSeparator overrides the path separator in printed output.
	PathSeparator string
	// ActualPathSeparator is the effective separator (default or override).
	ActualPathSeparator string

	// MaxResults limits the number of results. nil = unlimited.
	MaxResults *int

	// StripCwdPrefix removes the leading "./" of relative results.
	StripCwdPrefix bool

	// IgnoreContain skips directories that contain a named entry.
	IgnoreContain []string

	// AbsolutePath makes results absolute.
	AbsolutePath bool
	// contains filtered or unexported fields
}

Config holds every option controlling a search. The zero value is not valid; build it through the CLI layer or the SDK helpers which apply defaults.

func (*Config) IsPrinting

func (c *Config) IsPrinting() bool

IsPrinting reports whether results are being printed (no command set).

type DirEntry

type DirEntry struct {
	// contains filtered or unexported fields
}

DirEntry represents a single discovered filesystem entry. It lazily resolves metadata to avoid unnecessary syscalls.

func (*DirEntry) Depth

func (e *DirEntry) Depth() int

Depth returns the traversal depth (root children are depth 1).

func (*DirEntry) Info

func (e *DirEntry) Info() (os.FileInfo, error)

Info returns the (lazily-loaded) file info, using lstat semantics.

func (*DirEntry) IsDir

func (e *DirEntry) IsDir() bool

IsDir reports whether the entry is a directory.

func (*DirEntry) Path

func (e *DirEntry) Path() string

Path returns the entry's path as discovered.

func (*DirEntry) StrippedPath

func (e *DirEntry) StrippedPath(cfg *Config) string

StrippedPath returns the path as it should be displayed to the user.

func (*DirEntry) Type

func (e *DirEntry) Type() fs.FileMode

Type returns the file mode type bits, or 0 if unavailable.

type ExitCode

type ExitCode int

ExitCode mirrors fd's process exit codes.

const (
	// ExitSuccess indicates success.
	ExitSuccess ExitCode = 0
	// ExitGeneralError indicates a general error.
	ExitGeneralError ExitCode = 1
)

type FileType

type FileType int

FileType enumerates the entry kinds that can be filtered with --type.

const (
	// TypeFile matches regular files.
	TypeFile FileType = iota
	// TypeDirectory matches directories.
	TypeDirectory
	// TypeSymlink matches symbolic links.
	TypeSymlink
	// TypeBlockDevice matches block devices.
	TypeBlockDevice
	// TypeCharDevice matches character devices.
	TypeCharDevice
	// TypeExecutable matches executable files.
	TypeExecutable
	// TypeEmpty matches empty files or directories.
	TypeEmpty
	// TypeSocket matches sockets.
	TypeSocket
	// TypePipe matches named pipes (FIFOs).
	TypePipe
)

type FileTypes

type FileTypes struct {
	Files           bool
	Directories     bool
	Symlinks        bool
	BlockDevices    bool
	CharDevices     bool
	Sockets         bool
	Pipes           bool
	ExecutablesOnly bool
	EmptyOnly       bool
}

FileTypes describes which entry kinds should be shown.

type Finder

type Finder struct {
	// contains filtered or unexported fields
}

Finder executes searches according to a Config.

func New

func New(cfg *Config) (*Finder, error)

New constructs a Finder, compiling derived state (extension regexes) from the configuration. Patterns must already be compiled and assigned via SetPatterns or by the SDK helpers.

func (*Finder) Config

func (f *Finder) Config() *Config

Config returns the underlying configuration.

func (*Finder) Find

func (f *Finder) Find(ctx context.Context, paths []string) ([]string, error)

Find runs the search and returns all matching paths, sorted lexicographically. It is a convenience wrapper around Stream that collects results.

func (*Finder) Run

func (f *Finder) Run(ctx context.Context, paths []string) ExitCode

Run executes the search and performs fd's CLI-style output: printing results (with buffering/sorting and colorization), running commands (-x/-X), or reporting match presence in quiet mode. It returns a process exit code.

func (*Finder) SetPatterns

func (f *Finder) SetPatterns(patterns []*regexp.Regexp)

SetPatterns assigns the compiled search patterns. All patterns must match for an entry to be reported.

func (*Finder) Stream

func (f *Finder) Stream(ctx context.Context, paths []string) (<-chan Result, <-chan error)

Stream runs the search and streams results over a channel. A second channel surfaces non-fatal traversal errors. Both channels are closed when the search completes. Cancel ctx to stop early.

type LsColors

type LsColors struct {
	// contains filtered or unexported fields
}

LsColors maps filesystem indicators and filename patterns to ANSI styles.

func ParseLsColors

func ParseLsColors(s string) *LsColors

ParseLsColors parses an LS_COLORS-format string.

type Result

type Result struct {
	Path  string
	Entry *DirEntry
}

Result is a single matched entry surfaced through the SDK.