osutil

package
v0.74.2 Latest Latest
Warning

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

 Go to latest Published: Apr 20, 2026 License: MIT Imports: 20 Imported by: 46

Documentation

Overview

Package osutil implements some OS utility functions.

Package osutil implements some OS utility functions.

Index

Constants

View Source 
const (
	ModeDir0700  os.FileMode = 0700
	ModeDir0755  os.FileMode = 0755
	ModeFile0600 os.FileMode = 0600
	ModeFile0644 os.FileMode = 0644
)
View Source 
const (
	ColDir  = "dir"
	ColName = "name"
	ColPath = "path"
	ColSize = "size"
)
View Source 
const (
	NewlinePOSIX       = "\n"
	NewlineMSFT        = "\r\n"
	NewlineAPPLClassic = "\r"
)

Variables

View Source 
var (
	ErrWriterNotInitialized = errors.New("bufio.Writer not initialized")
	ErrFileNotInitialized   = errors.New("os.File not initialized")
)
View Source 
var ErrPathTraversal = errors.New("path contains '..' traversal sequence")

ErrPathTraversal is returned when a path contains ".." sequences.

Functions

func AbsFilepath 

func AbsFilepath(path string) (string, error)

AbsFilepath returns an absolute filepath, using the user's current / home directory if indicated in the filepath string.

func AbsPathSecure added in v0.74.1 

func AbsPathSecure(path string) (string, error)

AbsPathSecure validates that a path contains no traversal sequences, then returns the absolute, cleaned path. This is the recommended function for library code that needs fully qualified paths.

func CleanPathSecure added in v0.74.1 

func CleanPathSecure(path string) (string, error)

CleanPathSecure validates that a path contains no traversal sequences, then returns the cleaned path. This is the recommended function for library code receiving paths from callers.

For CLI entry points where the user explicitly provides paths, use filepath.Clean directly with a //nolint:gosec comment.

func CloseFileWithError added in v0.44.0 

func CloseFileWithError(file *os.File, err error) error

func CopyFile added in v0.44.0 

func CopyFile(src, dst string) error

func CopyFileSecure added in v0.74.1 

func CopyFileSecure(src, dst string) error

CopyFileSecure copies a file from src to dst after validating the destination path does not contain path traversal sequences (".."). This is the recommended function for library code that receives destination paths from callers.

For CLI entry points where the user explicitly provides paths, use CopyFile directly with a //nolint:gosec comment instead.

func CreateFileWithLines 

func CreateFileWithLines(filename string, lines []string, lineSuffix string, useBuffer bool) error

CreateFileWithLines creates a file and writes lines to it. It will optionally add a `lineSuffix` (e.g. `"\n"`) and use `bufio`.

func DirFromPath added in v0.44.0 

func DirFromPath(path string) (string, error)

func DirRemoveAllChildren added in v0.44.0 

func DirRemoveAllChildren(dir string) error

func EmptyAll 

func EmptyAll(name string) error

EmptyAll will delete all contents of a directory, leaving the provided directory. This is different from os.Remove which also removes the directory provided.

func EnvExists 

func EnvExists(fields ...string) (missing []string, haveAll bool)

func EnvHeader added in v0.63.2 

func EnvHeader(rx *regexp.Regexp) http.Header

func EnvMap added in v0.63.2 

func EnvMap(rx *regexp.Regexp) map[string]string

EnvMap returns a map[string]string of environment variables that match a regular expression.

func Exists 

func Exists(name string) (bool, error)

Exists checks whether the named filepath exists or not for a file or directory.

func FileInfoModAge added in v0.44.0 

func FileInfoModAge(fi os.FileInfo) time.Duration

FileInfoModAge returns the file last modification age as a time.Duration.

func FileInfosNames added in v0.44.0 

func FileInfosNames(fis []os.FileInfo) []string

func FileInfosSplit added in v0.44.0 

func FileInfosSplit(all []os.FileInfo, inclDotDirs bool) ([]os.FileInfo, []os.FileInfo)

func FileModAge 

func FileModAge(filename string) (time.Duration, error)

FileModAge returns a time.Duration representing the age of the named file from FileInfo.ModTime().

func FileModAgeLTE added in v0.44.0 

func FileModAgeLTE(filename string, s string) (bool, error)

func FilenModAgeGTE added in v0.44.0 

func FilenModAgeGTE(filename string, s string) (bool, error)

func Filenames added in v0.41.5 

func Filenames(name string, rx *regexp.Regexp, inclEmptyFiles, absPath bool) ([]string, error)

Filenames returns a list of filenames for files only (no directories). If a directory is provided it will return a list of filenames in that directory. If a `Regexp` or `inclEmptyFiles` params are provided, those will be use to filter the output.

func FilenamesFilterSizeGTZero added in v0.44.0 

func FilenamesFilterSizeGTZero(filepaths ...string) []string

func FinfosToFilepaths 

func FinfosToFilepaths(dir string, fis []os.FileInfo) []string

FinfosToFilepaths returns a slice of string from a directory and sli=ce of `os.FileInfo`.

func GetFileInfo 

func GetFileInfo(path string) (os.FileInfo, error)

GetFileInfo returns an os.FileInfo from a filepath.

func GoPath added in v0.37.9 

func GoPath(parts ...string) string

func IsDir 

func IsDir(name string) (bool, error)

func IsFile 

func IsFile(name string, sizeGtZero bool) (bool, error)

IsFile verifies a path exists and is a file. It will optionally check if a file is not empty. An os file not exists check can be done with os.IsNotExist(err) which acts on error from os.Stat().

func MustFileSize added in v0.47.0 

func MustFileSize(filename string) int64

MustFileSize returns value of `FileInfo.Size()` which is length in bytes for regular files; system-dependent for others. It returns `-1` if an error is encountered.

func MustUserHomeDir 

func MustUserHomeDir(subdirs ...string) string

func NewLine added in v0.47.0 

func NewLine() string

NewLine uses `os.PathSeparator` to determine the newline characters for the local system.

func ReadDirFilesSecure added in v0.74.1 

func ReadDirFilesSecure(dir string) (map[string][]byte, error)

ReadDirFilesSecure reads all files from a directory recursively using os.Root for symlink-safe operations. This prevents TOCTOU race conditions where symlinks could be swapped during traversal (gosec G122).

Returns a map of relative paths to file contents. Paths use forward slashes regardless of OS.

Requires Go 1.24+ for os.Root support.

func ReadDirRxSubmatch 

func ReadDirRxSubmatch(dir string, rx *regexp.Regexp, subMatchIdx uint32, inclDirs, inclFiles, inclEmptyFiles bool) (map[string][]os.DirEntry, error)

ReadDirRxSubmatch takes a directory, regular expression and boolean to indicate whether to include zero size files and returns the greatest of a single match in the regular expression.

func ReadDirRxSubmatchCaptureGreatest 

func ReadDirRxSubmatchCaptureGreatest(dir string, rx *regexp.Regexp, subMatchIdx uint32, inclDirs, inclFiles, inclEmptyFiles bool) (string, error)

ReadDirRxSubmatchCaptureGreatest takes a directory, regular expression and returns the greatest of a single submatch in the regular expression.

func ReadDirRxSubmatchCaptures 

func ReadDirRxSubmatchCaptures(dir string, rx *regexp.Regexp, subMatchIdx uint32, inclDirs, inclFiles, inclEmptyFiles bool) ([]string, error)

ReadDirRxSubmatchCaptures takes a directory, regular expression and returns the greatest of captures from the regular expression.

func ReadDirRxSubmatchEntriesGreatest 

func ReadDirRxSubmatchEntriesGreatest(dir string, rx *regexp.Regexp, subMatchIdx uint32, inclDirs, inclFiles, inclEmptyFiles bool) ([]os.DirEntry, error)

func ReadDirSplit added in v0.44.0 

func ReadDirSplit(dirname string, inclDotDirs bool) ([]os.FileInfo, []os.FileInfo, error)

ReadDirSplit returnsa slides of `os.FileInfo` for directories and files. Note: this isn't as necessary any more since `os.ReadDir()` returns a slice of `os.DirEntry{}` which has a `IsDir()` func.

func ReadFileByLine added in v0.41.0 

func ReadFileByLine(name string, lineFunc func(idx uint, line string) error) error

func ReadFileJSON added in v0.44.0 

func ReadFileJSON(file string, v any) error

ReadFileJSON reads and unmarshals a file.

func ReadSubdirMax 

func ReadSubdirMax(dir string, rx *regexp.Regexp) (os.DirEntry, error)

func ReadSubdirMin 

func ReadSubdirMin(dir string, rx *regexp.Regexp) (os.DirEntry, error)

func SanitizePath added in v0.73.2 

func SanitizePath(path string, opts *SanitizeOpts) (string, error)

SanitizePath cleans and validates a file path for safe use in subprocesses. It expands ~ to the user's home directory, cleans the path, resolves it to an absolute path, and optionally validates existence and type constraints.

This function is useful for sanitizing user-provided paths before passing them to exec.Command or similar functions.

func SortDirEntriesModTime added in v0.37.18 

func SortDirEntriesModTime(files DirEntries)

SortDirEntriesModTime sorts `DirEntries` by last modified time. It will panic if an entry cannot retrieve `FileInfo` information.

func SplitBest added in v0.44.0 

func SplitBest(path string) (dir, file string, err error)

func SplitBetter added in v0.44.0 

func SplitBetter(path string) (dir, file string)

func ValidateNoTraversal added in v0.74.1 

func ValidateNoTraversal(path string) error

ValidateNoTraversal checks that a path does not contain ".." sequences. This should be used in library code to reject paths that could escape a base directory. Returns ErrPathTraversal if ".." is found.

Note: This validates the literal path string, not the resolved path. Use filepath.EvalSymlinks for symlink-aware validation.

func VisitFiles added in v0.39.5 

func VisitFiles(name string, visitFunc func(dir string, info fs.FileInfo) error) error

func VisitPath added in v0.37.18 

func VisitPath(dir string, rx *regexp.Regexp, inclDirs, inclFiles, inclEmptyFiles bool, visitFunc func(dir string) error) error

VisitPath visit a directory and all subdirectories, executing the supplied `visitFunc` on each.

func WriteFileJSON added in v0.44.0 

func WriteFileJSON(filepath string, data any, perm os.FileMode, prefix, indent string) error

func WriteFileReader added in v0.45.0 

func WriteFileReader(filename string, r io.Reader, perm os.FileMode) (err error)

func WriteFileSecure added in v0.74.1 

func WriteFileSecure(path string, data []byte, perm os.FileMode) error

WriteFileSecure writes data to the specified path after validating it does not contain path traversal sequences (".."). This is the recommended function for library code that receives paths from callers.

For CLI entry points where the user explicitly provides paths, use os.WriteFile directly with a //nolint:gosec comment instead.

Types

type DirEntries 

type DirEntries []os.DirEntry

DirEntries provides utility functions for `[]os.DirEntry`. Use as `entries := osutil.DirEntries(slice)`.

func ReadDirMore 

func ReadDirMore(dir string, rx *regexp.Regexp, inclDirs, inclFiles, inclEmptyFiles bool) (DirEntries, error)

func (DirEntries) Dirs added in v0.49.0 

func (entries DirEntries) Dirs() DirEntries

func (DirEntries) Files added in v0.49.0 

func (entries DirEntries) Files() DirEntries

func (DirEntries) Infos 

func (entries DirEntries) Infos() ([]os.FileInfo, error)

Infos returns a `[]os.FileInfo` slice.

func (DirEntries) Len 

func (entries DirEntries) Len() int

func (DirEntries) Less 

func (entries DirEntries) Less(i, j int) bool

func (DirEntries) Names 

func (entries DirEntries) Names(dir string) []string

Names returns a slice of entry names. It can optionally add the directory path and sort the values.

func (DirEntries) Sort 

func (entries DirEntries) Sort()

Sort sorts dir entries by name.

func (DirEntries) Swap 

func (entries DirEntries) Swap(i, j int)

func (DirEntries) WriteFileNames added in v0.33.0 

func (entries DirEntries) WriteFileNames(filename, dir string, perm os.FileMode) error

WriteFileNames writes a text file with filenames, one per line.

type DirEntriesMore 

type DirEntriesMore []DirEntryMore

func ReadDirFiles 

func ReadDirFiles(dir string, inclDirs, inclFiles, recursive bool) (DirEntriesMore, error)

func (DirEntriesMore) Rows 

func (entries DirEntriesMore) Rows(inclDirs, inclFiles bool, cols ...string) ([][]string, error)

type DirEntryMore 

type DirEntryMore struct {
	Dir      string
	DirEntry fs.DirEntry
}

func (DirEntryMore) Row 

func (em DirEntryMore) Row(cols ...string) ([]string, error)

type EnvVar 

type EnvVar struct {
	Key   string
	Value string
}

func Env 

func Env() []EnvVar

type FileInfoMore 

type FileInfoMore struct {
	FileInfo os.FileInfo
	ModAge   time.Duration
}

FileInfoMore provides a struct hold FileInfo with additional information.

func NewFileInfoMoreFromPath 

func NewFileInfoMoreFromPath(path string) (FileInfoMore, error)

NewFileInfoMoreFromPath returns a FileInfoMore struct populatig both FileInfo and ModAge (last modification time).

type FileType added in v0.44.0 

type FileType int
const (
	File FileType = iota
	Directory
	Any
)

type FileWriter added in v0.44.0 

type FileWriter struct {
	File   *os.File
	Writer *bufio.Writer
}

func NewFileWriter added in v0.44.0 

func NewFileWriter(path string) (FileWriter, error)

func (*FileWriter) Close added in v0.44.0 

func (fw *FileWriter) Close() error

func (*FileWriter) WriteBytes added in v0.46.0 

func (fw *FileWriter) WriteBytes(b []byte) (int, error)

func (*FileWriter) WriteString added in v0.46.0 

func (fw *FileWriter) WriteString(addLinefeed bool, s ...string) (int, error)

func (*FileWriter) WriteStringf added in v0.46.0 

func (fw *FileWriter) WriteStringf(addLinefeed bool, format string, a ...any) (int, error)

type SanitizeOpts added in v0.73.2 

type SanitizeOpts struct {
	// MustExist requires the path to exist on the filesystem.
	MustExist bool
	// MustBeFile requires the path to be a regular file (not a directory).
	MustBeFile bool
	// MustBeDir requires the path to be a directory.
	MustBeDir bool
	// AllowedExts restricts the path to files with these extensions (e.g., ".mp4", ".srt").
	// Extensions should include the leading dot. If empty, any extension is allowed.
	AllowedExts []string
}

SanitizeOpts configures path sanitization behavior.

Source Files

View all Source files

Directories

Path Synopsis
cmd
cp command
file_sizes command
subdirs command

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.