fsutil

Documentation

Overview

Package fsutil provides the filesystem primitives gskill relies on for safe, reproducible mutations: atomic file writes, same-filesystem staging temp dirs, and a symlink-or-copy activation that records the method actually used.

Index

• func CopyDir(src, dst string) error
• func ImportDir(root, key, srcDir string) (string, error)
• func KeyPath(root, key string) string
• func SymlinkOrCopy(src, dst string) (symlinked bool, err error)
• func TempDir(parent, pattern string) (string, error)
• func WriteFileAtomic(path string, data []byte, perm fs.FileMode) (err error)
• type Lock
  • func Acquire(ctx context.Context, path string, mode LockMode, timeout time.Duration) (*Lock, error)
  • func (l *Lock) Release() error
• type LockMode

Functions

func CopyDir

func CopyDir(src, dst string) error

CopyDir recursively copies the tree rooted at src into dst, preserving file permissions (including the exec bit) and recreating symlinks as symlinks without following them.

func ImportDir

func ImportDir(root, key, srcDir string) (string, error)

ImportDir atomically copies srcDir into the content-addressed location for key under root and returns the final path. It is idempotent: an entry that already exists is left untouched.

func KeyPath

func KeyPath(root, key string) string

KeyPath maps a content key such as "sha256:abcd" to a directory under root, splitting the algorithm prefix into its own subdirectory.

func SymlinkOrCopy

func SymlinkOrCopy(src, dst string) (symlinked bool, err error)

SymlinkOrCopy activates src at dst, preferring a symlink and falling back to a recursive copy when the filesystem rejects symlinks. It reports whether a symlink was used (false means a copy was made), which the caller records as the actual install mode.

func TempDir

func TempDir(parent, pattern string) (string, error)

TempDir creates a uniquely named temporary directory under parent (creating parent if needed), so staging happens on the same filesystem as the eventual destination and can be promoted with a rename.

func WriteFileAtomic

func WriteFileAtomic(path string, data []byte, perm fs.FileMode) (err error)

WriteFileAtomic writes data to path atomically. It creates parent directories as needed, writes to a temp file on the same filesystem, fsyncs it, then renames over path so readers never observe a partial file.

Types

type Lock

type Lock struct {
	// contains filtered or unexported fields
}

Lock is a held filesystem lock. Release must be called to free it.

func Acquire

func Acquire(ctx context.Context, path string, mode LockMode, timeout time.Duration) (*Lock, error)

Acquire obtains a lock at path with the given mode, retrying until timeout. On timeout it returns an error that maps to the cache/lock-failure exit code 12 (FR-021). LockNone returns immediately without touching the filesystem.

func (*Lock) Release

func (l *Lock) Release() error

Release frees the lock. It is safe to call on a LockNone lock.

type LockMode

type LockMode int

LockMode selects the locking discipline for Acquire.

const (
	// LockExclusive takes a single-writer lock; mutating commands use this.
	LockExclusive LockMode = iota
	// LockShared takes a multi-reader lock; read-only commands may use this.
	LockShared
	// LockNone performs no locking and never blocks.
	LockNone
)