fileutils

Documentation

Index

• Variables
• func ComputeFileHash(fs opctx.FS, hashType HashType, filePath string) (string, error)
• func CopyDirRecursive(dryRunnable opctx.DryRunnable, fs opctx.FS, sourceDirPath, destDirPath string, ...) (err error)
• func CopyDirRecursiveCrossFS(dryRunnable opctx.DryRunnable, sourceFS opctx.FS, sourceDirPath string, ...) (err error)
• func CopyFile(dryRunnable opctx.DryRunnable, fs opctx.FS, sourcePath, destPath string, ...) error
• func CopyFileCrossFS(dryRunnable opctx.DryRunnable, sourceFS opctx.FS, sourcePath string, ...) (err error)
• func DirExists(fs opctx.FS, path string) (bool, error)
• func Exists(fs opctx.FS, path string) (bool, error)
• func Glob(fs opctx.FS, pattern string, opts ...doublestar.GlobOption) ([]string, error)
• func IsDirEmpty(fs opctx.FS, path string) (bool, error)
• func MkdirAll(fs opctx.FS, path string) error
• func MkdirTemp(fs opctx.FS, dir, pattern string) (string, error)
• func MkdirTempInTempDir(fs opctx.FS, pattern string) (string, error)
• func ReadDir(fs opctx.FS, name string) (entries []os.FileInfo, err error)
• func ReadFile(fs opctx.FS, filename string) ([]byte, error)
• func RemoveAllAndUpdateErrorIfNil(fs opctx.FS, path string, errorToUpdate *error)
• func SkipExistingFiles(destFS opctx.FS, destPath string) (bool, error)
• func SymLinkOrCopy(dryRunnable opctx.DryRunnable, fs opctx.FS, sourcePath, destPath string, ...) error
• func ValidateFileHash(dryRunnable opctx.DryRunnable, fs opctx.FS, hashType HashType, filePath string, ...) error
• func ValidateFilename(filename string) error
• func WrapEmbedFS(embedFS *embed.FS) opctx.FS
• func WriteFile(fs opctx.FS, path string, data []byte, perm os.FileMode) error
• type CopyDirOptions
• type CopyFileOptions
• type FileUpdateWriter
  • func NewFileUpdateWriter(fs opctx.FS, destFilePath string) (result *FileUpdateWriter, err error)
  • func (a *FileUpdateWriter) Commit() (err error)
  • func (a *FileUpdateWriter) Write(p []byte) (n int, err error)
• type HashType

Variables

var (
	// ErrReadOnlyEmbedFS is returned when a write operation is attempted on an embedded FS.
	ErrReadOnlyEmbedFS = errors.New("embed filesystem is read-only")

	// ErrUnimplementedForEmbedFS is returned when an operation is not implemented for an embedded FS.
	ErrUnimplementedForEmbedFS = errors.New("operation unimplemented for embed filesystem")
)

Functions

func ComputeFileHash

func ComputeFileHash(fs opctx.FS, hashType HashType, filePath string) (string, error)

Computes the hash of the file located at filePath using the specified hashType; returns the hash in hex string form.

func CopyDirRecursive

func CopyDirRecursive(
	dryRunnable opctx.DryRunnable, fs opctx.FS,
	sourceDirPath, destDirPath string,
	options CopyDirOptions,
) (err error)

Recursively copies a directory. May preserve mode bits if "options" says so but does *not* preserve ownership, timestamps, or other metadata. *Does* follow symlinks. Is enlightened to skip copying in dry-run mode.

func CopyDirRecursiveCrossFS

func CopyDirRecursiveCrossFS(
	dryRunnable opctx.DryRunnable,
	sourceFS opctx.FS, sourceDirPath string,
	destFS opctx.FS, destDirPath string,
	options CopyDirOptions,
) (err error)

Recursively copies a directory, potentially across two opctx.FS filesystem instances. May preserve mode bits if "options" says so but does *not* preserve ownership, timestamps, or other metadata. *Does* follow symlinks. Is *not* enlightened to skip copying in dry-run mode.

func CopyFile

func CopyFile(dryRunnable opctx.DryRunnable, fs opctx.FS, sourcePath, destPath string, options CopyFileOptions) error

Copies the contents of an existing file to a new file at the given destination path. May preserve mode bits if "options" says so but does *not* preserve ownership, timestamps, or other metadata. *Does* follow symlinks. Is enlightened to skip copying in dry-run mode.

func CopyFileCrossFS

func CopyFileCrossFS(
	dryRunnable opctx.DryRunnable,
	sourceFS opctx.FS, sourcePath string,
	destFS opctx.FS, destPath string,
	options CopyFileOptions,
) (err error)

Copies the contents of an existing file to a new file at the given destination path, potentially across two opctx.FS filesystem instances. May preserve mode bits if "options" says so but does *not* preserve ownership, timestamps, or other metadata. *Does* follow symlinks. Is *not* enlightened to skip copying in dry-run mode.

func DirExists

func DirExists(fs opctx.FS, path string) (bool, error)

Adaptation of afero.DirExists that works with opctx.FS. Checks if a directory exists at the given path.

func Exists

func Exists(fs opctx.FS, path string) (bool, error)

Adaptation of afero.Exists that works with opctx.FS. Checks if a file or directory exists at the given path.

func Glob

func Glob(fs opctx.FS, pattern string, opts ...doublestar.GlobOption) ([]string, error)

Adaptation of filepath.Glob that works with opctx.FS and also uses the doublestar package to supports standard double-star globs ('**').

func IsDirEmpty

func IsDirEmpty(fs opctx.FS, path string) (bool, error)

IsDirEmpty checks if a directory exists and is empty.

func MkdirAll

func MkdirAll(fs opctx.FS, path string) error

NOTE: The sole point of this function is to provide a single place to decide the correct permissions for the directory.

func MkdirTemp

func MkdirTemp(fs opctx.FS, dir, pattern string) (string, error)

Adaptation of os.TempDir that works with opctx.FS.

func MkdirTempInTempDir

func MkdirTempInTempDir(fs opctx.FS, pattern string) (string, error)

Wrapper that calls MkdirTemp with the default temp dir.

func ReadDir

func ReadDir(fs opctx.FS, name string) (entries []os.FileInfo, err error)

Readdir is an adaptation of os.ReadDir that works with opctx.FS; notably, it returns a slice of os.FileInfo instead of fs.DirEntry.

func ReadFile

func ReadFile(fs opctx.FS, filename string) ([]byte, error)

Adaptation of os.ReadFile that works with opctx.FS.

func RemoveAllAndUpdateErrorIfNil

func RemoveAllAndUpdateErrorIfNil(fs opctx.FS, path string, errorToUpdate *error)

Utility function intended for use in defer statements; calls opctx.FS.RemoveAll and, on error, updates the error value pointed to by errorToUpdate. Intentionally does *not* update the error pointed to by errorToUpdate on success cases, to avoid clobbering an error that may already be stored there.

func SkipExistingFiles

func SkipExistingFiles(destFS opctx.FS, destPath string) (bool, error)

SkipExistingFiles is a [CopyDirOptions.FileFilter] that skips files already present at the destination path, allowing pre-existing files to take precedence.

func SymLinkOrCopy

func SymLinkOrCopy(
	dryRunnable opctx.DryRunnable,
	fs opctx.FS,
	sourcePath, destPath string,
	options CopyFileOptions,
) error

SymLinkOrCopy attempts to symlink a file, falling back to copy if symlinking is not supported or fails. Symlinks are only attempted on real OS filesystems (afero.OsFs). For other filesystem types (e.g., in-memory filesystems used in tests), this function logs a warning and falls back directly to copying.

func ValidateFileHash

func ValidateFileHash(
	dryRunnable opctx.DryRunnable,
	fs opctx.FS,
	hashType HashType,
	filePath string,
	expectedHash string,
) error

ValidateFileHash validates that the file stored at filePath has contents matching the expectedHash using the specified hashType algorithm.

func ValidateFilename

func ValidateFilename(filename string) error

ValidateFilename ensures a filename is safe for use as a destination path. It rejects filenames that could escape the destination directory via path traversal.

func WrapEmbedFS

func WrapEmbedFS(embedFS *embed.FS) opctx.FS

WrapEmbedFS returns an opctx.FS that wraps an embed.FS instance.

func WriteFile

func WriteFile(fs opctx.FS, path string, data []byte, perm os.FileMode) error

Adaptation of os.WriteFile that works with opctx.FS.

Types

type CopyDirOptions

type CopyDirOptions struct {
	CopyFileOptions

	// FileFilter is an optional callback invoked for each file before copying.
	// It receives the destination filesystem and the destination file path.
	// If it returns false, the file is skipped. If nil, all files are copied.
	FileFilter func(destFS opctx.FS, destPath string) (bool, error)
}

Options regarding recursive directory copying.

type CopyFileOptions

type CopyFileOptions struct {
	// Whether or not to preserve POSIX mode bits on files. Does *not* apply to directories.
	PreserveFileMode bool
}

Options regarding file copying.

type FileUpdateWriter

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

A file writer capable of atomically applying its updates to files (provided that the underlying filesystem supports it).

func NewFileUpdateWriter

func NewFileUpdateWriter(fs opctx.FS, destFilePath string) (result *FileUpdateWriter, err error)

Used for updating files. On "real" system filesystems, uses renameio package to atomically update files. On in-memory and other filesystems, degrades to a non-atomic update.

func (*FileUpdateWriter) Commit

func (a *FileUpdateWriter) Commit() (err error)

Commits pending writes to the destination file.

func (*FileUpdateWriter) Write

func (a *FileUpdateWriter) Write(p []byte) (n int, err error)

Implements io.Writer, delegating to the inner file writer.

type HashType

type HashType string

HashType represents a type of hash used for source file verification.

const (
	// HashTypeMD5 represents the MD5 hash algorithm.
	// Note: MD5 is cryptographically weak and should only be used for legacy compatibility.
	HashTypeMD5 HashType = "md5"

	// HashTypeSHA256 represents the SHA-256 hash algorithm.
	HashTypeSHA256 HashType = "sha256"

	// HashTypeSHA512 represents the SHA-512 hash algorithm.
	HashTypeSHA512 HashType = "sha512"
)