go-file-utils

Go Report Card CI Documentation License: MIT

A modern, high-performance, zero-dependency Go filesystem utility library. Designed for production services, CLI applications, data pipelines, and distributed tools requiring reliable, secure, and cross-platform file operations.


๐ŸŒŸ Key Features


๐Ÿ“ฆ Installation

go get github.com/Techwasti-Infotech/go-file-utils

๐Ÿš€ Quick Start & Usage Examples

1. Basic Filesystem Operations

package main

import (
	"fmt"
	"github.com/Techwasti-Infotech/go-file-utils"
)

func main() {
	// Check existence
	if fileutils.Exists("configs/settings.json") {
		fmt.Println("Config file exists!")
	}

	// Ensure parent directory exists and touch a file
	_ = fileutils.EnsureDir("logs/2026/03", 0o755)
	_ = fileutils.Touch("logs/2026/03/app.log")

	// Safe copy with timestamps preserved
	_ = fileutils.CopyFile("logs/2026/03/app.log", "logs/backup.log", fileutils.CopyFileOptions{
		Overwrite:          true,
		PreserveTimestamps: true,
	})

	// Retrieve clean file metadata
	info, _ := fileutils.GetInfo("logs/backup.log")
	fmt.Printf("File: %s, Size: %d bytes\n", info.Name, info.Size)
}

2. Atomic Writes & Streaming Line Readers

// Atomically write data without risking partial writes during crashes
data := []byte(`{"status": "ok"}`)
err := fileutils.WriteFileAtomic("configs/app.json", data, 0o644)

// Stream large log files line by line
err = fileutils.ReadLines("logs/large.log", func(line string) (bool, error) {
    if strings.Contains(line, "FATAL") {
        fmt.Println("Alert:", line)
        return false, nil // Stop reading early
    }
    return true, nil // Continue reading
})

3. Advanced File Finder

// Find all Go files larger than 1KB modified in the last 24 hours
files, err := fileutils.Find(".", fileutils.SearchFilter{
    Extensions:    []string{".go"},
    MinSize:       1024,
    ModifiedAfter: time.Now().Add(-24 * time.Hour),
    SkipHidden:    true,
    OnlyFiles:     true,
})

4. Secure Archiving (Zip & Tar.gz)

// Compress an entire directory tree
_ = fileutils.Zip("data/reports", "data/reports.zip")

// Extract with automatic Zip Slip security defense
_ = fileutils.Unzip("data/reports.zip", "data/extracted")

5. Checksums & Verification

// Calculate streaming SHA256 checksum
hash, _ := fileutils.FileSHA256("data/reports.zip")

// Verify integrity against expected checksum
match, _ := fileutils.VerifyFileChecksum("data/reports.zip", fileutils.HashSHA256, hash)

6. Process File Locking

// Hold exclusive atomic lock during critical section
err := fileutils.WithLock("database.sqlite", 5*time.Second, func() error {
    // Perform isolated write
    return nil
})

๐Ÿ’ก Runnable Examples & Cookbook

We provide a complete suite of runnable standalone example programs inside the examples/ directory:

Run any example directly with:

go run ./examples/01_basic_fs

๐Ÿ“– API Documentation & Website

Browse the interactive online documentation hosted on GitHub Pages: ๐Ÿ‘‰ https://techwasti-infotech.github.io/go-file-utils/

Additional reference documents:


๐Ÿงช Testing

Run all unit tests with data race detector and coverage report:

go test -v -race -cover ./...

๐Ÿ“„ License

This library is distributed under the terms of the MIT License. See LICENSE for details.