filesystem

Documentation

Overview

Package filesystem provides various filesystem utility methods either not provided by the Go standard library or requiring a more optimized implementation. It also provides filesystem watching facilities.

Index

• Constants
• Variables
• func DecomposesUnicode(path string) (bool, error)
• func DeviceID(info os.FileInfo) (uint64, error)
• func DirectoryContents(path string) ([]os.FileInfo, error)
• func GetOwnership(info os.FileInfo) (int, int, error)
• func IsAtomicOperationFileName(name string) bool
• func IsExecutabilityProbeFileName(name string) bool
• func IsUnicodeProbeFileName(name string) bool
• func Mutagen(create bool, subpath ...string) (string, error)
• func Normalize(path string) (string, error)
• func PreservesExecutability(path string) (bool, error)
• func RenameFileAtomic(oldPath, newPath string) error
• func SetOwnership(path string, uid, gid int) error
• func Walk(root string, visitor filepath.WalkFunc) error
• func Watch(context context.Context, root string, events chan struct{}, mode WatchMode, ...)
• func WriteFileAtomic(path string, data []byte, permissions os.FileMode) error
• type Locker
  • func NewLocker(path string, permissions os.FileMode) (*Locker, error)
  • func (l *Locker) Lock(block bool) error
  • func (l *Locker) Unlock() error
• type WatchMode
  • func (m WatchMode) Description() string
  • func (WatchMode) EnumDescriptor() ([]byte, []int)
  • func (x WatchMode) String() string
  • func (m WatchMode) Supported() bool
  • func (m *WatchMode) UnmarshalText(textBytes []byte) error

Constants

const (
	// DefaultPollingInterval is the default watch polling interval, in seconds.
	DefaultPollingInterval = 10
)

const (

	// MutagenDirectoryName is the name of the Mutagen control directory inside
	// the user's home directory.
	MutagenDirectoryName = ".mutagen"
)

Variables

var HomeDirectory string

HomeDirectory is the cached path to the current user's home directory.

var MutagenConfigurationPath string

MutagenConfigurationPath is the path to the Mutagen configuration file.

var WatchMode_name = map[int32]string{
	0: "WatchDefault",
	1: "WatchPortable",
	2: "WatchForcePoll",
}

var WatchMode_value = map[string]int32{
	"WatchDefault":   0,
	"WatchPortable":  1,
	"WatchForcePoll": 2,
}

Functions

func DecomposesUnicode

func DecomposesUnicode(path string) (bool, error)

DecomposesUnicode determines whether or not the filesystem on which the directory at the specified path resides decomposes Unicode filenames.

func DeviceID

func DeviceID(info os.FileInfo) (uint64, error)

DeviceID extracts the device ID from a stat result.

func DirectoryContents

func DirectoryContents(path string) ([]os.FileInfo, error)

DirectoryContents returns the contents of the directory at the specified path. The ordering of the contents is non-deterministic.

func GetOwnership

func GetOwnership(info os.FileInfo) (int, int, error)

GetOwnership returns the owning user and group IDs from file metadata.

func IsAtomicOperationFileName

func IsAtomicOperationFileName(name string) bool

IsAtomicOperationFileName determines whether or not a file name (not a file path) is the name of an intermediate temporary file used in an atomic operation.

func IsExecutabilityProbeFileName

func IsExecutabilityProbeFileName(name string) bool

IsExecutabilityProbeFileName determines whether or not a file name (not a file path) is the name of an executability preservation probe file.

func IsUnicodeProbeFileName

func IsUnicodeProbeFileName(name string) bool

IsUnicodeProbeFileName determines whether or not a file name (not a file path) is the name of an Unicode decomposition probe file.

func Mutagen

func Mutagen(create bool, subpath ...string) (string, error)

Mutagen computes (and optionally creates) subdirectories inside the Mutagen directory (~/.mutagen).

func Normalize

func Normalize(path string) (string, error)

Normalize normalizes a path, expanding home directory tildes, converting it to an absolute path, and cleaning the result.

func PreservesExecutability

func PreservesExecutability(path string) (bool, error)

PreservesExecutability determines whether or not the filesystem on which the directory at the specified path resides preserves POSIX executability bits.

func RenameFileAtomic

func RenameFileAtomic(oldPath, newPath string) error

RenameFileAtomic performs an atomic file rename. In the simplest case, it's a simple alias for os.Rename. However, if moving a file across filesystems, it will fall back to a copy/rename combination that should still approximate atomicity (at least in terms of swapping the destination file contents). It does NOT support renaming directories, only files. It takes inspiration from: https://github.com/golang/dep/blob/4ad9f4ec24012607dc247ca24528e3224d61519a/fs.go#L80

func SetOwnership

func SetOwnership(path string, uid, gid int) error

SetOwnership sets the owning user and group IDs for the specified path.

func Walk

func Walk(root string, visitor filepath.WalkFunc) error

Walk provides a faster implementation of path/filepath.Walk with slightly different semantics. In particular, it only walks directory contents after metadata for the directory has been collected and does not sort entries by name. It gains speed by avoiding sorting and, more importantly, using os.File.Readdir for vastly more efficient traversal on Windows.

func Watch

func Watch(context context.Context, root string, events chan struct{}, mode WatchMode, pollInterval uint32)

TODO: Document that this function closes the events channel when the watch is cancelled. TODO: Document that this function will always succeed in one way or another (it doesn't have any total failure modes) and won't exit until the associated context is cancelled. TODO: Document that the events channel must be buffered.

func WriteFileAtomic

func WriteFileAtomic(path string, data []byte, permissions os.FileMode) error

WriteFileAtomic writes a file to disk in an atomic fashion by using an intermediate temporary file that is swapped in place using a rename operation.

Types

type Locker

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

Locker provides file locking facilities.

func NewLocker

func NewLocker(path string, permissions os.FileMode) (*Locker, error)

NewLocker attempts to create a lock with the file at the specified path, creating the file if necessary. The lock is returned in an unlocked state.

func (*Locker) Lock

func (l *Locker) Lock(block bool) error

Lock attempts to acquire the file lock.

func (*Locker) Unlock

func (l *Locker) Unlock() error

Unlock releases the file lock.

type WatchMode

type WatchMode int32

WatchMode specifies the mode for filesystem watching.

const (
	// WatchMode_WatchDefault represents an unspecified watch mode. It should be
	// converted to one of the following values based on the desired default
	// behavior.
	WatchMode_WatchDefault WatchMode = 0
	// WatchMode_WatchPortable specifies that native recursive watching should
	// be used to monitor paths on systems that support it if those paths fall
	// under the home directory. In these cases, a watch on the entire home
	// directory is established and filtered for events pertaining to the
	// specified path. On all other systems and for all other paths, poll-based
	// watching is used.
	WatchMode_WatchPortable WatchMode = 1
	// WatchMode_WatchForcePoll specifies that only poll-based watching should
	// be used.
	WatchMode_WatchForcePoll WatchMode = 2
)

func (WatchMode) Description

func (m WatchMode) Description() string

Description returns a human-readable description of a watch mode.

func (WatchMode) EnumDescriptor

func (WatchMode) EnumDescriptor() ([]byte, []int)

func (WatchMode) String

func (x WatchMode) String() string

func (WatchMode) Supported

func (m WatchMode) Supported() bool

Supported indicates whether or not a particular watch mode is a valid, non-default value.

func (*WatchMode) UnmarshalText

func (m *WatchMode) UnmarshalText(textBytes []byte) error

UnmarshalText implements the text unmarshalling interface used when loading from TOML files.