fs

package module

v1.4.1 Latest Latest Go to latest Published: Feb 20, 2026 License: MIT Imports: 22 Imported by: 48

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/go-zoox/fs

Links

Open Source Insights

README ¶

fs - A FileSystem Abstraction System for Go

Installation

To install the package, run:

go get github.com/go-zoox/fs

Getting Started

f := fs.OpenFile("/path/to/file")

Examples

Atomic write (SafeWriteFile):

if err := fs.SafeWriteFile("/path/to/config.json", data); err != nil {
    log.Fatal(err)
}

List files by pattern (Glob):

matches, err := fs.Glob("/tmp/*.go")

Create and extract archives:

// Create tar.gz from directory
fs.CreateTarGz("backup.tar.gz", []string{"/path/to/dir"})
// Extract zip
fs.ExtractZip("archive.zip", "/dest/dir")

Watch directory (context, callback, debounced):

ctx := context.Background()
fs.WatchDir(ctx, []string{"/path/to/dir"}, func(err error, event, filepath string) {
    if err != nil { log.Print(err); return }
    log.Printf("%s %s", event, filepath)
})

List of all available functions

// Path
func Abs(path string) (string, error)
func BaseName(path string) string
func CleanPath(path string) string
func DirName(path string) string
func EnsureDir(path string) error
func ExtName(path string) string
func IsAbsPath(path string) bool
func JoinPath(paths ...string) string
func ReadSymlink(path string) (string, error)
func Rel(base, target string) (string, error)
func TmpDirPath() string
func TmpFilePath() string

// File
func AppendFile(path string, data []byte) error
func Checksum(path string, algorithm string) (string, error)
func CopyFile(srcPath string, dstPath string) error
func CreateFile(path string) (*os.File, error)
func MoveFile(srcPath string, dstPath string) error
func Open(path string) (*os.File, error)
func OpenFile(path string, flagAndPerm ...interface{}) (*os.File, error)
func ReadFile(srcPath string) ([]byte, error)
func ReadFileAsString(srcPath string) (string, error)
func ReadFileLines(srcPath string) ([]string, error)
func ReadFileRange(path string, offset, length int64) ([]byte, error)
func RemoveFile(path string) error
func RenameFile(srcPath string, dstPath string) error
func SafeWriteFile(path string, data []byte) error
func Stat(path string) (os.FileInfo, error)
func Touch(path string) error
func WriteFile(path string, data []byte) error
func Size(path string) int64

// Directory
func CopyDir(srcPath string, dstPath string, opts ...CopyDirOption) error
func CreateDir(path string, perm ...iofs.FileMode) error
func DirSize(path string) (int64, error)
func Glob(pattern string) ([]string, error)
func GlobDir(dir string, pattern string) ([]string, error)
func ListDir(path string) ([]iofs.FileInfo, error)
func ListDirNames(path string) ([]string, error)
func MoveDir(srcPath string, dstPath string) error
func RemoveDir(path string) error
func RenameDir(srcPath string, dstPath string) error
func Walk(path string, fn iofs.WalkDirFunc) error
func WalkDir(path string, fn iofs.WalkDirFunc) error
func WatchDir(ctx context.Context, paths []string, callback func(err error, event string, filepath string)) error

// Common (file or dir)
func Copy(srcPath, dstPath string) error
func CreateSymbolicLink(srcPath, dstPath string) error
func Mkdir(path string, perm ...iofs.FileMode) error
func Mkdirp(path string, perm ...iofs.FileMode) error
func Move(srcPath, dstPath string) error
func Remove(path string) error
func Rename(srcPath, dstPath string) error

// Is / permission
func IsDir(path string) bool
func IsEmpty(path string) bool
func IsExist(path string) bool
func IsExecutable(path string) bool
func IsFile(path string) bool
func IsReadable(path string) bool
func IsSymbolicLink(path string) bool
func IsWritable(path string) bool
func Chmod(name string, mode os.FileMode) error
func Chown(name string, uid, gid int) error

// Extract / archive
func ExtractZip(zipPath, destDir string) error
func ExtractTarGz(stream io.Reader, destDir string, logHandler func(filename string)) error
func CreateTarGz(destPath string, sources []string) error

License

GoZoox is released under the MIT License.

Documentation ¶

Index ¶

Variables
func Abs(path string) (string, error)
func AppendFile(path string, data []byte) error
func BaseName(path string) string
func Checksum(path string, algorithm string) (string, error)
func Chmod(name string, mode os.FileMode) error
func Chown(name string, uid, gid int) error
func CleanPath(path string) string
func ConfigDir() string
func Copy(srcPath, dstPath string) error
func CopyDir(srcPath string, dstPath string, opts ...CopyDirOption) error
func CopyFile(srcPath string, dstPath string) error
func CreateDir(path string, perm ...iofs.FileMode) error
func CreateFile(path string) (*os.File, error)
func CreateSymbolicLink(srcPath, dstPath string) error
func CreateTarGz(destPath string, sources []string) error
func CurrentDir() string
func DirName(path string) string
func DirSize(path string) (int64, error)
func EnsureDir(path string) error
func ExtName(path string) string
func ExtractTarGz(stream io.Reader, destDir string, logHandler func(filename string)) error
func ExtractZip(zipPath, destDir string) error
func Glob(pattern string) ([]string, error)
func GlobDir(dir string, pattern string) ([]string, error)
func HomeDir() string
func IsAbsPath(path string) bool
func IsDir(path string) bool
func IsEmpty(path string) bool
func IsExecutable(path string) bool
func IsExist(path string) bool
func IsFile(path string) bool
func IsReadable(path string) bool
func IsSymbolicLink(path string) bool
func IsWritable(path string) bool
func JoinConfigDir(appName string, configName ...string) string
func JoinCurrentDir(relativePath string) string
func JoinHomeDir(relativePath string) string
func JoinPath(paths ...string) string
func ListDir(path string) ([]iofs.FileInfo, error)
func ListDirNames(path string) ([]string, error)
func Merge(filePath string, parts []*FilePart) error
func Mkdir(path string, perm ...iofs.FileMode) error
func Mkdirp(path string, perm ...iofs.FileMode) error
func Move(srcPath, dstPath string) error
func MoveDir(srcPath string, dstPath string) error
func MoveFile(srcPath, dstPath string) error
func Open(path string) (*os.File, error)
func OpenFile(path string, flagAndPerm ...interface{}) (*os.File, error)
func ReadFile(srcPath string) ([]byte, error)
func ReadFileAsString(srcPath string) (string, error)
func ReadFileLines(srcPath string) ([]string, error)
func ReadFileRange(path string, offset, length int64) ([]byte, error)
func ReadSymlink(path string) (string, error)
func Rel(base, target string) (string, error)
func Remove(path string) error
func RemoveDir(path string) error
func RemoveFile(path string) error
func Rename(srcPath, dstPath string) error
func RenameDir(srcPath string, dstPath string) error
func RenameFile(srcPath, dstPath string) error
func SafeWriteFile(path string, data []byte) error
func Size(path string) int64
func Stat(path string) (os.FileInfo, error)
func SystemConfigDir() string
func TmpDirPath() string
func TmpFilePath() string
func Touch(path string) error
func UserConfigDir() string
func Walk(path string, fn iofs.WalkDirFunc) error
func WalkDir(path string, fn iofs.WalkDirFunc) error
func WatchDir(ctx context.Context, paths []string, ...) error
func WriteFile(path string, data []byte) (err error)
type CopyDirOption
type FilePart

Constants ¶

This section is empty.

Variables ¶

View Source

var Version = "1.4.1"

Version is the current version of the package.

Functions ¶

func Abs ¶ added in v1.4.1

func Abs(path string) (string, error)

Abs returns an absolute representation of path.

func AppendFile ¶ added in v1.3.5

func AppendFile(path string, data []byte) error

AppendFile appends a file.

func BaseName ¶

func BaseName(path string) string

BaseName returns the last element of path.

func Checksum ¶ added in v1.4.1

func Checksum(path string, algorithm string) (string, error)

Checksum computes a hash of the file and returns its hex-encoded string. Algorithm is case-insensitive: "sha256", "md5" are supported.

func Chmod ¶

func Chmod(name string, mode os.FileMode) error

Chmod changes the mode of the named file to mode.

func Chown ¶

func Chown(name string, uid, gid int) error

Chown changes the numeric uid and gid of the named file.

func CleanPath ¶ added in v1.4.1

func CleanPath(path string) string

CleanPath returns the shortest path name equivalent to path by purely lexical processing.

func ConfigDir ¶ added in v1.3.2

func ConfigDir() string

ConfigDir returns the config dir by user

if user is root, return system config dir
if user is common user, return user home config dir

func CopyDir ¶

func CopyDir(srcPath string, dstPath string, opts ...CopyDirOption) error

CopyDir copies a directory. Optional CopyDirOption can exclude paths by pattern (e.g. ".git", "node_modules").

func CreateSymbolicLink ¶

func CreateSymbolicLink(srcPath, dstPath string) error

CreateSymbolicLink creates a symbolic link

func CreateTarGz ¶ added in v1.4.1

func CreateTarGz(destPath string, sources []string) error

CreateTarGz creates a gzipped tar archive at destPath from the given sources (files and directories).

func CurrentDir ¶

func CurrentDir() string

CurrentDir returns the path of the current directory.

func DirName ¶

func DirName(path string) string

DirName returns all but the last element of path.

func DirSize ¶ added in v1.4.1

func DirSize(path string) (int64, error)

DirSize returns the total size in bytes of all regular files under dir (recursive). Symbolic links are not followed.

func EnsureDir ¶ added in v1.4.1

func EnsureDir(path string) error

EnsureDir ensures the directory for path exists. If path looks like a file (has a non-empty base name that is not "." or ".."), it ensures the parent directory exists. If path is a directory path, it ensures that directory exists. Typically used before writing a file: EnsureDir(filePath).

func ExtName ¶

func ExtName(path string) string

ExtName returns the file extension of path.

func ExtractTarGz ¶ added in v1.2.5

func ExtractTarGz(stream io.Reader, destDir string, logHandler func(filename string)) error

ExtractTarGz extracts a tar.gz file.

func ExtractZip ¶ added in v1.4.1

func ExtractZip(zipPath, destDir string) error

ExtractZip extracts a zip file at zipPath into destDir.

func Glob ¶ added in v1.4.1

func Glob(pattern string) ([]string, error)

Glob returns the names of all files matching pattern (see filepath.Glob).

func GlobDir ¶ added in v1.4.1

func GlobDir(dir string, pattern string) ([]string, error)

GlobDir returns paths under dir that match pattern (pattern is relative to dir). Returned paths are joined with dir (absolute if dir is absolute).

func HomeDir ¶ added in v1.3.2

func HomeDir() string

HomeDir returns the user home directory.

func IsAbsPath ¶

func IsAbsPath(path string) bool

IsAbsPath checks whether the path is absolute.

func IsDir ¶

func IsDir(path string) bool

IsDir checks whether the path is a directory.

func IsEmpty ¶

func IsEmpty(path string) bool

IsEmpty checks whether the dir/file is empty.

func IsExecutable ¶ added in v1.4.1

func IsExecutable(path string) bool

IsExecutable checks whether the path has any execute bit set (user, group, or other). It uses the mode from Stat; useful for scripts and binaries.

func IsExist ¶

func IsExist(path string) bool

IsExist checks whether a file or directory exists.

func IsFile ¶

func IsFile(path string) bool

IsFile checks whether the path is a file.

func IsReadable ¶ added in v1.4.1

func IsReadable(path string) bool

IsReadable checks whether the current user can read the path (file or directory). It attempts to open the path for reading; success means readable.

func IsSymbolicLink ¶

func IsSymbolicLink(path string) bool

IsSymbolicLink checks whether the path is a symbolic link.

func IsWritable ¶ added in v1.4.1

func IsWritable(path string) bool

IsWritable checks whether the current user can write to the path. For a file it tries to open for append; for a directory it tries to create and remove a temp file. Behavior is best-effort and may vary by platform.

func JoinConfigDir ¶ added in v1.3.2

func JoinConfigDir(appName string, configName ...string) string

JoinConfigDir returns the config of appName + configName. configName default is config.yml.

func JoinCurrentDir ¶ added in v1.3.2

func JoinCurrentDir(relativePath string) string

JoinCurrentDir returns the path which relative with current dir.

func JoinHomeDir ¶ added in v1.3.2

func JoinHomeDir(relativePath string) string

JoinHomeDir returns the path which relative with homedir.

func JoinPath ¶

func JoinPath(paths ...string) string

JoinPath joins any number of path elements into a single path, adding a

func ListDir ¶

func ListDir(path string) ([]iofs.FileInfo, error)

ListDir lists the files in a directory.

func ListDirNames ¶ added in v1.4.1

func ListDirNames(path string) ([]string, error)

ListDirNames returns the names of the entries in the directory (not full paths).

func Merge ¶

func Merge(filePath string, parts []*FilePart) error

Merge merges files into one file.

func Mkdir ¶

func Mkdir(path string, perm ...iofs.FileMode) error

Mkdir creates a directory.

func Mkdirp ¶

func Mkdirp(path string, perm ...iofs.FileMode) error

Mkdirp creates a deep directory.

func Move ¶

func Move(srcPath, dstPath string) error

Move moves a file or directory

func MoveDir ¶

func MoveDir(srcPath string, dstPath string) error

MoveDir moves a directory.

func MoveFile ¶

func MoveFile(srcPath, dstPath string) error

MoveFile moves a file.

func Open ¶

func Open(path string) (*os.File, error)

Open opens a file, if file not found, creates it.

func OpenFile ¶

func OpenFile(path string, flagAndPerm ...interface{}) (*os.File, error)

OpenFile opens a file.

func ReadFile ¶

func ReadFile(srcPath string) ([]byte, error)

ReadFile reads a file.

func ReadFileAsString ¶

func ReadFileAsString(srcPath string) (string, error)

ReadFileAsString reads a file as string.

func ReadFileLines ¶

func ReadFileLines(srcPath string) ([]string, error)

ReadFileLines reads a file by line.

func ReadFileRange ¶ added in v1.4.1

func ReadFileRange(path string, offset, length int64) ([]byte, error)

ReadFileRange reads up to length bytes from path starting at offset. If length <= 0, reads from offset to end of file.

func ReadSymlink ¶ added in v1.4.1

func ReadSymlink(path string) (string, error)

ReadSymlink returns the destination of the named symbolic link.

func Rel ¶ added in v1.4.1

func Rel(base, target string) (string, error)

Rel returns a relative path that is lexically equivalent to target when joined to base.

func Remove ¶

func Remove(path string) error

Remove removes a file or directory

func RemoveDir ¶

func RemoveDir(path string) error

RemoveDir removes a directory.

func RemoveFile ¶

func RemoveFile(path string) error

RemoveFile removes a file.

func Rename ¶

func Rename(srcPath, dstPath string) error

Rename renames a file or directory

func RenameDir ¶

func RenameDir(srcPath string, dstPath string) error

RenameDir renames a directory.

func RenameFile ¶

func RenameFile(srcPath, dstPath string) error

RenameFile renames a file.

func SafeWriteFile ¶ added in v1.4.1

func SafeWriteFile(path string, data []byte) error

SafeWriteFile writes data to path atomically: write to a temp file in the same directory then rename.

func Size ¶

func Size(path string) int64

Size returns the size of the file.

func Stat ¶

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

Stat returns the FileInfo structure describing file.

func SystemConfigDir ¶ added in v1.3.12

func SystemConfigDir() string

SystemConfigDir returns the system config directory, which is /etc

func TmpDirPath ¶

func TmpDirPath() string

TmpDirPath returns the path of the temporary directory.

func TmpFilePath ¶

func TmpFilePath() string

TmpFilePath returns the path of the temporary file.

func Touch ¶ added in v1.4.1

func Touch(path string) error

Touch creates an empty file if path does not exist; otherwise updates its modification time to now.

func UserConfigDir ¶ added in v1.3.12

func UserConfigDir() string

UserConfigDir returns the user config directory, which is $HOME/.config

func Walk ¶

func Walk(path string, fn iofs.WalkDirFunc) error

Walk walks the files in a directory.

func WalkDir ¶

func WalkDir(path string, fn iofs.WalkDirFunc) error

WalkDir walks the files in a directory.

func WatchDir ¶ added in v1.3.0

func WatchDir(ctx context.Context, paths []string, callback func(err error, event string, filepath string)) error

WatchDir watches the changes of files.

func WriteFile ¶

func WriteFile(path string, data []byte) (err error)

WriteFile writes a file.

Types ¶

type CopyDirOption ¶ added in v1.4.1

type CopyDirOption struct {
	// Exclude is a list of filepath.Match patterns; paths with any segment matching are skipped.
	// Matching directories are skipped entirely (SkipDir).
	Exclude []string
}

CopyDirOption configures CopyDir behavior.

type FilePart ¶

type FilePart struct {
	Path string
	//
	Index int
}

FilePart represents a part of a file.

Source Files ¶

View all Source files

Directories ¶

Path	Synopsis
type
git/credentials
hosts
ini
json
passwd
toml
yaml

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL