walk

Documentation

Overview

Package walk implements parallel directory traversal.

Index

• type Config
• type Entry
  • func (e Entry) DisplayPath() string
  • func (e *Entry) ResolveInfo() (fs.FileInfo, error)
• type EntryKind
• type Walker
  • func NewWalker(fsys fs.FS, cfg Config, engine *ignore.Engine) *Walker
  • func (w *Walker) Run(ctx context.Context, paths []string, fileCh chan<- Entry)
  • func (w *Walker) RunWithErrors(ctx context.Context, paths []string, fileCh chan<- Entry, errorCh chan<- error)

Types

type Config

type Config struct {
	// Threads is the number of walker workers.
	// 0 means auto (GOMAXPROCS).
	Threads int
	// FollowSymlinks traverses symbolic links.
	FollowSymlinks bool
	// MaxFileSize skips files larger than this. 0 means unlimited.
	MaxFileSize int64
	// EmitDirs emits directory entries in addition to files. Supplied directory
	// roots are traversal anchors and are not emitted.
	EmitDirs bool
	// EmitSymlinks emits symbolic links as entries when FollowSymlinks is false.
	EmitSymlinks bool
	// LazyFileInfo omits regular-file metadata from emitted entries until the
	// consumer resolves it through Entry.ResolveInfo or Entry.File. The default
	// keeps metadata eager.
	LazyFileInfo bool
	// IgnoreDanglingSymlinks skips not-found errors from followed symbolic links.
	IgnoreDanglingSymlinks bool
	// MinDepth filters emitted entries below this root-relative depth.
	MinDepth int
	// MaxDepth filters emitted entries deeper than this root-relative depth.
	// A non-zero value enables the limit; MaxDepthSet is required for an
	// explicit zero-depth limit.
	MaxDepth int
	// MaxDepthSet enables MaxDepth when it is zero.
	MaxDepthSet bool
	// SkipFileRef omits constructing capability-backed fsref.Ref file references.
	// Used when file content is not read.
	SkipFileRef bool
}

Config holds walker options.

type Entry

type Entry struct {
	// File is the capability-backed file reference for file entries. It is nil
	// for directory entries.
	File fsref.Ref
	// Path is the stable user-facing path.
	Path string
	// Info is the metadata discovered during walking. It may be nil when the
	// walker is configured with LazyFileInfo for a regular file.
	Info fs.FileInfo
	// Kind identifies whether this is a file or directory.
	Kind EntryKind
	// Symlink reports whether the entry path itself is a symbolic link. Info
	// describes the link target when symlink following is enabled.
	Symlink bool
	// Depth is relative to the supplied traversal root. Explicit file targets
	// have depth zero; children of a directory root start at depth one.
	Depth int
	// contains filtered or unexported fields
}

Entry represents a filesystem entry found during traversal.

func (Entry) DisplayPath

func (e Entry) DisplayPath() string

DisplayPath returns the stable user-facing path for the entry.

func (*Entry) ResolveInfo

func (e *Entry) ResolveInfo() (fs.FileInfo, error)

ResolveInfo materializes metadata omitted by LazyFileInfo.

type EntryKind

type EntryKind uint8

EntryKind identifies the kind of filesystem entry.

const (
	// EntryFile identifies a non-directory entry.
	EntryFile EntryKind = iota
	// EntryDirectory identifies a directory entry.
	EntryDirectory
)

type Walker

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

Walker performs parallel directory traversal, emitting file and optional directory entries.

func NewWalker

func NewWalker(fsys fs.FS, cfg Config, engine *ignore.Engine) *Walker

NewWalker creates a walker with the given config and ignore engine. If fsys is nil, it defaults to the local OS filesystem.

func (*Walker) Run

func (w *Walker) Run(ctx context.Context, paths []string, fileCh chan<- Entry)

Run walks paths and sends entries to fileCh. fileCh is closed when all work is done. Traversal errors are skipped to preserve the original walker contract; use RunWithErrors to receive them.

func (*Walker) RunWithErrors

func (w *Walker) RunWithErrors(ctx context.Context, paths []string, fileCh chan<- Entry, errorCh chan<- error)

RunWithErrors walks paths, sending entries to fileCh and operational errors to errorCh. Both channels are closed when traversal completes. A nil errorCh preserves Run's skip-error behavior.