fs

Documentation

Overview

Package fs provides cross-platform filesystem utilities.

This package addresses platform differences in:

• File permissions (Unix uses mode bits, Windows largely ignores them)
• Path separators (Unix uses /, Windows uses \)
• Path validation for security (preventing directory traversal)

Index

• Constants
• Variables
• func Birthtime(path string) (time.Time, error)
• func BirthtimeInfo(info os.FileInfo) time.Time
• func BirthtimeSupported() bool
• func IsCaseSensitive() bool
• func JoinNormalized(elem ...string) string
• func JoinOS(elem ...string) string
• func MkdirAll(path string, perm os.FileMode) error
• func MkdirAllPrivate(path string) error
• func NormalizeLineEndings(s string) string
• func NormalizePath(p string) string
• func OSPath(p string) string
• func PathEqual(path1, path2 string) bool
• func PathHasPrefix(path, prefix string) bool
• func SafeJoin(base, rel string) (string, error)
• func ValidatePath(p string) error
• func ValidatePathStrict(p string) error
• func WriteFile(filename string, data []byte, perm os.FileMode) error
• func WriteFilePrivate(filename string, data []byte) error

Constants

const (
	// DefaultDirPerm is the default permission for directories (rwxr-xr-x).
	DefaultDirPerm os.FileMode = 0755

	// DefaultFilePerm is the default permission for files (rw-r--r--).
	DefaultFilePerm os.FileMode = 0644

	// PrivateDirPerm is for directories that should only be accessible by owner (rwx------).
	PrivateDirPerm os.FileMode = 0700

	// PrivateFilePerm is for files that should only be accessible by owner (rw-------).
	PrivateFilePerm os.FileMode = 0600

	// ExecutablePerm is for executable files (rwxr-xr-x).
	ExecutablePerm os.FileMode = 0755
)

Default permission constants. These follow Unix conventions; Windows ignores permission bits but the values are still useful for cross-platform code consistency.

Variables

var (
	// ErrPathTraversal is returned when a path attempts directory traversal.
	ErrPathTraversal = errors.New("oscompat/fs: path traversal detected")

	// ErrEmptyPath is returned when an empty path is provided.
	ErrEmptyPath = errors.New("oscompat/fs: empty path")

	// ErrAbsolutePath is returned when an absolute path is provided where relative is expected.
	ErrAbsolutePath = errors.New("oscompat/fs: absolute path not allowed")
)

Common errors.

Functions

func Birthtime

func Birthtime(path string) (time.Time, error)

Birthtime returns the file's creation time if available. On platforms without birthtime support, it falls back to modification time.

Platform behavior:

• macOS: Uses Birthtimespec from syscall.Stat_t
• Windows: Uses CreationTime from Win32FileAttributeData
• Linux: Falls back to ModTime (birthtime not reliably available)

func BirthtimeInfo

func BirthtimeInfo(info os.FileInfo) time.Time

BirthtimeInfo returns the file's creation time from an existing FileInfo. This is more efficient when you already have the FileInfo. On platforms without birthtime support, it falls back to modification time.

func BirthtimeSupported

func BirthtimeSupported() bool

BirthtimeSupported returns true if the platform supports file birthtime. macOS and Windows support birthtime; Linux does not reliably support it.

func IsCaseSensitive

func IsCaseSensitive() bool

IsCaseSensitive returns whether the current OS has case-sensitive file paths. Returns false on Windows (case-insensitive), true on Unix/macOS (case-sensitive). Note: macOS HFS+ is case-insensitive by default, but APFS can be either. This function returns the typical/default behavior for each platform.

func JoinNormalized

func JoinNormalized(elem ...string) string

JoinNormalized joins path elements and returns a normalized (forward-slash) path. This is useful for building storage keys or URIs.

func JoinOS

func JoinOS(elem ...string) string

JoinOS joins path elements using OS-specific separators. This is a convenience wrapper around filepath.Join.

func MkdirAll

func MkdirAll(path string, perm os.FileMode) error

MkdirAll creates a directory and all parent directories with the specified permissions. This is a convenience wrapper that uses DefaultDirPerm if perm is 0.

func MkdirAllPrivate

func MkdirAllPrivate(path string) error

MkdirAllPrivate creates a private directory (owner-only access).

func NormalizeLineEndings

func NormalizeLineEndings(s string) string

NormalizeLineEndings converts Windows line endings (CRLF) to Unix (LF). This is useful when reading text files that may have been created on Windows or when files are checked out with CRLF line endings on Windows via git.

func NormalizePath

func NormalizePath(p string) string

NormalizePath converts OS-specific path separators to forward slashes. This is useful for storing paths in a platform-independent format. The path is also cleaned (redundant separators removed, . and .. resolved). Backslashes are converted to forward slashes on all platforms.

func OSPath

func OSPath(p string) string

OSPath converts forward slashes to OS-specific path separators. This is the inverse of NormalizePath.

func PathEqual

func PathEqual(path1, path2 string) bool

PathEqual compares two paths for equality, using case-insensitive comparison on Windows and case-sensitive comparison on Unix. Both paths are normalized before comparison.

func PathHasPrefix

func PathHasPrefix(path, prefix string) bool

PathHasPrefix checks if path has the given prefix, using case-insensitive comparison on Windows and case-sensitive comparison on Unix. Both paths are normalized before comparison.

func SafeJoin

func SafeJoin(base, rel string) (string, error)

SafeJoin safely joins a base path with a relative path, preventing traversal. Returns an error if the result would escape the base directory.

func ValidatePath

func ValidatePath(p string) error

ValidatePath checks a path for directory traversal attacks. It returns an error if the path:

• Is empty
• Contains ".." that would escape the root
• Is absolute (starts with / or drive letter on Windows)

This function handles both forward slashes and backslashes for Windows compatibility.

func ValidatePathStrict

func ValidatePathStrict(p string) error

ValidatePathStrict is like ValidatePath but also rejects paths starting with ".". This is useful when hidden files/directories should not be allowed.

func WriteFile

func WriteFile(filename string, data []byte, perm os.FileMode) error

WriteFile writes data to a file with the specified permissions. This is a convenience wrapper that uses DefaultFilePerm if perm is 0.

func WriteFilePrivate

func WriteFilePrivate(filename string, data []byte) error

WriteFilePrivate writes data to a private file (owner-only access).