fsx
package module
This package is not in the latest version of its module.
Go to latest Published: Aug 18, 2026 License: Apache-2.0Details
-
Valid go.mod file
The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
-
Redistributable license
Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
-
Tagged version
Modules with tagged versions give importers more predictable builds.
-
Stable version
When a project reaches major version v1 it is considered stable.
- Learn more about best practices
Repository
Links
Open Source Insights
README
¶
fsx
fsx is a small Go package for filesystem helpers that sit just above os and path/filepath. It is designed for applications that need compact, easy-to-review helpers for expanded user paths, containment checks, file predicates, extension matching, and atomic writes.
The package is standard-library-only, has no external module dependencies, and targets the latest Go toolchain version declared in go.mod. It intentionally keeps one short package name instead of exposing broad utils packages.
Features
- User path expansion for leading ~ and $HOME
- Path existence checks for files, directories, and any filesystem entry
- Directory containment checks that normalize relative traversal
- Case-insensitive file extension matching
- Atomic file replacement with permissions
- Zero third-party dependencies
- Apache-2.0 licensed
Installation
go get github.com/slashdevops/fsx
Update to the latest available version:
go get -u github.com/slashdevops/fsx
Requirements
- Go 1.26.3 or newer, matching the latest Go version declared by the module
- No external Go modules or third-party dependencies
Quick Start
package main
import (
"fmt"
"log"
"os"
"path/filepath"
"github.com/slashdevops/fsx"
)
func main() {
configPath := fsx.ExpandPath("~/app/config.yaml")
if !fsx.HasExtension(configPath, "yaml") {
log.Fatal("config file must be YAML")
}
if err := os.MkdirAll(filepath.Dir(configPath), 0o755); err != nil {
log.Fatal(err)
}
if err := fsx.WriteFileAtomic(configPath, []byte("enabled: true\n"), 0o600); err != nil {
log.Fatal(err)
}
fmt.Println(filepath.Base(configPath))
}
API
ExpandPath
func ExpandPath(path string) string
ExpandPath replaces a leading ~ with the current user's home directory and replaces $HOME references with the HOME environment variable. Empty paths are returned unchanged.
configPath := fsx.ExpandPath("~/app/config.yaml")
Exists
func Exists(path string) bool
Exists reports whether a file, directory, or other filesystem entry exists. The path is expanded before it is checked.
if fsx.Exists("~/app/config.yaml") {
// read config
}
IsDir
func IsDir(path string) bool
IsDir reports whether the expanded path exists and is a directory.
if !fsx.IsDir("~/app") {
return errors.New("app directory does not exist")
}
IsFile
func IsFile(path string) bool
IsFile reports whether the expanded path exists and is a regular file.
if !fsx.IsFile("~/app/config.yaml") {
return errors.New("config file does not exist")
}
IsWithin
func IsWithin(base, target string) bool
IsWithin reports whether target resolves to a path contained inside base. Both paths are expanded, cleaned, and made absolute before comparison. A target equal to base is considered within base.
This is useful before deleting or overwriting paths read from user-editable state files.
if !fsx.IsWithin(outputDir, stateFilePath) {
return fmt.Errorf("refusing to remove file outside output directory")
}
HasExtension
func HasExtension(path string, extensions ...string) bool
HasExtension reports whether path has one of the provided extensions. Matching is case-insensitive, extensions may be passed with or without a leading dot, and the path does not need to exist.
if !fsx.HasExtension("config.YAML", "yaml", "yml") {
return errors.New("config must be YAML")
}
Dir
func Dir(path string) string
Dir returns the directory component of path after expanding it.
dir := fsx.Dir("~/app/config.yaml")
WriteFileAtomic
func WriteFileAtomic(path string, data []byte, perm os.FileMode) error
WriteFileAtomic writes data to a temporary file in the destination directory, sets the requested permissions, and renames the temporary file over the target path.
The destination directory must already exist. If any step fails before the rename, the temporary file is removed.
if err := fsx.WriteFileAtomic("~/app/config.yaml", data, 0o600); err != nil {
return fmt.Errorf("save config: %w", err)
}
Quality Automation
The repository follows the same GitHub quality practices used by slashdevops/e5t:
- main.yml validates pushes to main with format checks, go vet, race-enabled tests, coverage, and go build.
- pr.yml runs the same quality gate for pull requests targeting main.
- codeql.yml runs CodeQL for Go and GitHub Actions on pushes, pull requests, and a weekly schedule.
- release.yml validates tagged releases and publishes GitHub releases with generated notes.
- dependabot.yml checks Go module and GitHub Actions updates weekly.
Project Structure
. |-- .github/ GitHub Actions, CodeQL, Dependabot, and release metadata |-- .golangci.yaml Optional local golangci-lint configuration |-- doc.go Package documentation rendered by pkg.go.dev |-- example_test.go Executable Go examples for documentation |-- fsx.go Public filesystem API |-- fsx_test.go Unit tests and benchmarks |-- go.mod Module definition with no external requirements |-- LICENSE Apache License 2.0 |-- README.md Project overview and usage guide `-- SECURITY.md Vulnerability reporting policy
Testing
Run the test suite:
go test ./...
Run benchmarks:
go test -bench=. ./...
Check test coverage:
go test -cover ./...
Run the same local quality checks used by CI:
go fix ./... go fmt ./... go vet ./... go test -race -coverprofile=/tmp/fsx-coverage.txt -covermode=atomic ./... go build ./...
License
fsx is licensed under the Apache License 2.0.
Contributing
Issues and pull requests are welcome at github.com/slashdevops/fsx. Please keep changes small, idiomatic, tested, documented, and dependency-free unless there is a clear reason to expand the project scope.
Documentation
¶
Overview ¶
Package fsx provides small filesystem helpers built only on the Go standard library and targets the latest Go toolchain version declared by the module.
The package focuses on behavior that is useful across command-line tools and services:
- expanding user-facing paths that start with ~ or contain $HOME
- checking whether paths exist and whether they are regular files or directories
- checking whether a regular file is marked readable or writable by its owner
- confirming that a path remains inside a base directory after normalization
- matching file extensions case-insensitively
- writing files atomically by replacing the destination with a temporary file
Path Expansion ¶
ExpandPath expands a leading ~ with the current user's home directory and replaces $HOME references with the HOME environment variable. If the home directory cannot be determined, the original path is returned unchanged.
Permission Predicates ¶
IsReadable and IsWritable inspect the file mode, not the effective access of the calling process. That is the portable answer the standard library can give: os.Stat exposes mode bits everywhere, while asking "can I open this?" needs access(2) or an attempted open. A caller that must be certain should open the file and handle the error — the answer can change between any check and the open regardless.
Atomic Writes ¶
WriteFileAtomic writes data to a temporary file in the destination directory, sets the requested permissions, and renames the temporary file over the target. This prevents readers from observing partially written file contents on the same filesystem.
Dependencies ¶
fsx has zero third-party dependencies and no external module requirements. It uses os, path/filepath, strings, and other standard library packages, and the module currently targets Go 1.26.3.
Index ¶
- func Dir(path string) string
- func Exists(path string) bool
- func ExpandPath(path string) string
- func HasExtension(path string, extensions ...string) bool
- func IsDir(path string) bool
- func IsFile(path string) bool
- func IsReadable(path string) bool
- func IsWithin(base, target string) bool
- func IsWritable(path string) bool
- func WriteFileAtomic(path string, data []byte, perm os.FileMode) error
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Dir ¶
Dir returns the directory component of path after expanding it with ExpandPath.
func Exists ¶
Exists reports whether a file, directory, or other filesystem entry exists.
The path is expanded with ExpandPath before it is checked. Empty paths and paths that cannot be statted return false.
func ExpandPath ¶
ExpandPath expands a user-facing filesystem path.
It replaces a leading ~ with the current user's home directory and replaces all $HOME references with the HOME environment variable. Empty paths are returned unchanged. If the home directory cannot be determined, the original path is returned unchanged.
Example ¶ExampleExpandPath demonstrates expanding a user-facing path.
package main
import (
"fmt"
"path/filepath"
"github.com/slashdevops/fsx"
)
func main() {
expanded := fsx.ExpandPath("~/config.yaml")
fmt.Println(filepath.IsAbs(expanded))
}
Output: true
func HasExtension ¶
HasExtension reports whether path has one of the provided extensions.
Extension matching is case-insensitive. Extensions may be passed with or without a leading dot. The path does not need to exist.
Example ¶ExampleHasExtension demonstrates extension matching.
package main
import (
"fmt"
"github.com/slashdevops/fsx"
)
func main() {
fmt.Println(fsx.HasExtension("config.YAML", "yaml", "json"))
fmt.Println(fsx.HasExtension("README", "md"))
}
Output: true false
func IsDir ¶
IsDir reports whether path exists and is a directory.
The path is expanded with ExpandPath before it is checked.
func IsFile ¶
IsFile reports whether path exists and is a regular file.
The path is expanded with ExpandPath before it is checked.
func IsReadable ¶ added in v0.0.2
IsReadable reports whether path is a regular file whose owner-read bit is set.
The check is on the file mode, not on the effective access of the calling process. That is the portable answer the standard library can give: os.Stat exposes mode bits on every platform, while asking "can *I* open this?" requires access(2) or an attempted open, neither of which is available portably without cgo or a platform build tag.
So this answers "is this file marked readable by its owner?" — which is what a tool validating a configuration path it created wants to know. A caller that must be certain it can read the file should open it and handle the error; a predicate cannot promise more than the mode bits it read, and the answer can change between the check and the open regardless.
An empty path, a missing path, and a path that is not a regular file all report false.
func IsWithin ¶
IsWithin reports whether target resolves to a path contained inside base.
Both paths are expanded, cleaned, and made absolute before comparison. The function returns false when either path is empty, either path cannot be resolved, or the relative path from base to target escapes base with "..". A target equal to base is considered within base.
Example ¶ExampleIsWithin demonstrates a containment check before deleting a file.
package main
import (
"fmt"
"os"
"path/filepath"
"github.com/slashdevops/fsx"
)
func main() {
base := filepath.Join(os.TempDir(), "workspace")
target := filepath.Join(base, "page.md")
fmt.Println(fsx.IsWithin(base, target))
fmt.Println(fsx.IsWithin(base, filepath.Join(base, "..", "escape.md")))
}
Output: true false
func IsWritable ¶ added in v0.0.2
IsWritable reports whether path is a regular file whose owner-write bit is set.
The same mode-bit semantics as IsReadable apply, and for the same reason. The case this exists for is a tool that will later rewrite a file it was handed — a configuration file, a lock file — and would rather refuse at validation time than fail halfway through a write.
An empty path, a missing path, and a path that is not a regular file all report false.
Example ¶
package main
import (
"fmt"
"os"
"path/filepath"
"github.com/slashdevops/fsx"
)
func main() {
dir, err := os.MkdirTemp("", "fsx-example-*")
if err != nil {
fmt.Println("error:", err)
return
}
defer os.RemoveAll(dir)
writable := filepath.Join(dir, "writable.yaml")
if err := os.WriteFile(writable, []byte("a: 1\n"), 0o644); err != nil {
fmt.Println("error:", err)
return
}
readOnly := filepath.Join(dir, "readonly.yaml")
if err := os.WriteFile(readOnly, []byte("a: 1\n"), 0o400); err != nil {
fmt.Println("error:", err)
return
}
fmt.Println(fsx.IsWritable(writable))
fmt.Println(fsx.IsWritable(readOnly))
fmt.Println(fsx.IsReadable(readOnly))
}
Output: true false true
func WriteFileAtomic ¶
WriteFileAtomic writes data to path by replacing it with a completed temporary file in the same directory.
The destination directory must already exist. The temporary file is created in that directory, written, closed, chmodded to perm, and renamed to path. If any step fails before the rename, the temporary file is removed.
Example ¶ExampleWriteFileAtomic demonstrates an atomic file replacement.
package main
import (
"fmt"
"log"
"os"
"path/filepath"
"github.com/slashdevops/fsx"
)
func main() {
dir, err := os.MkdirTemp("", "fsx-example-*")
if err != nil {
log.Fatal(err)
}
defer func() {
if err := os.RemoveAll(dir); err != nil {
log.Fatal(err)
}
}()
path := filepath.Join(dir, "config.txt")
if err := fsx.WriteFileAtomic(path, []byte("ready"), 0o600); err != nil {
log.Fatal(err)
}
data, err := os.ReadFile(path)
if err != nil {
log.Fatal(err)
}
fmt.Println(string(data))
}
Output: ready
Types ¶
This section is empty.
Source Files