Renameio

https://pkg.go.dev/github.com/google/renameio/v2
Admin
The renameio Go package provides a way to atomically create or replace a file or symbolic link,...
Tokens:2,188
Snippets:38
Trust Score:9.6
Update:2 months ago
Show doc for...
Tokens:
Raw
### WithExistingPermissions Option

Source: https://pkg.go.dev/github.com/google/renameio/v2

Attempts to use permissions from an existing target file, falling back to defaults if the file is missing or not a regular file.

```go
func WithExistingPermissions() Option
```

--------------------------------

### WithPermissions Option

Source: https://pkg.go.dev/github.com/google/renameio/v2

Sets target file permissions while respecting the umask.

```go
func WithPermissions(perm os.FileMode) Option
```

--------------------------------

### WithRoot Option

Source: https://pkg.go.dev/github.com/google/renameio/v2

Specifies a root directory for file operations, ignoring WithTempDir and $TMPDIR.

```go
func WithRoot(root *os.Root) Option
```

--------------------------------

### Atomic Symlink Creation with Root

Source: https://pkg.go.dev/github.com/google/renameio/v2

Wraps os.Symlink to atomically replace an existing symlink with the same name, using a specified root.

```go
func SymlinkRoot(root *os.Root, oldname, newname string) error
```

--------------------------------

### Atomic Symlink Creation

Source: https://pkg.go.dev/github.com/google/renameio/v2

Wraps os.Symlink to atomically replace an existing symlink with the same name.

```go
func Symlink(oldname, newname string) error
```

--------------------------------

### WithTempDir Option

Source: https://pkg.go.dev/github.com/google/renameio/v2

Configures the directory used for temporary, uncommitted files.

```go
func WithTempDir(dir string) Option
```

--------------------------------

### TempFile Function

Source: https://pkg.go.dev/github.com/google/renameio/v2

Creates a temporary file for atomic replacement, using default 0600 permissions.

```go
func TempFile(dir, path string) (*PendingFile, error)
```

--------------------------------

### NewPendingFile Function

Source: https://pkg.go.dev/github.com/google/renameio/v2

Creates a temporary file for atomic replacement at the specified path.

```go
func NewPendingFile(path string, opts ...Option) (*PendingFile, error)
```

--------------------------------

### WithStaticPermissions Option

Source: https://pkg.go.dev/github.com/google/renameio/v2

Sets target file permissions while ignoring the umask.

```go
func WithStaticPermissions(perm os.FileMode) Option
```

--------------------------------

### Option Interface

Source: https://pkg.go.dev/github.com/google/renameio/v2

Interface implemented by all configuration function return values.

```go
type Option interface {
	// contains filtered or unexported methods
}
```

--------------------------------

### Atomic File Writing

Source: https://pkg.go.dev/github.com/google/renameio/v2

Mirrors os.WriteFile to atomically replace an existing file with the provided data.

```go
func WriteFile(filename string, data []byte, perm os.FileMode, opts ...Option) error
```

--------------------------------

### NewPendingFile

Source: https://pkg.go.dev/github.com/google/renameio/v2

Creates a temporary file destined to atomically create or replace the destination file at the specified path.

```APIDOC
## func NewPendingFile(path string, opts ...Option) (*PendingFile, error)

### Description
Creates a temporary file destined to atomically creating or replacing the destination file at path.

### Parameters
- **path** (string) - Required - The destination path for the file.
- **opts** (...Option) - Optional - Configuration options for the file creation (e.g., WithPermissions, WithTempDir).

### Returns
- **(*PendingFile, error)** - A pointer to the created PendingFile or an error if creation fails.
```

--------------------------------

### PendingFile Struct

Source: https://pkg.go.dev/github.com/google/renameio/v2

Represents a temporary file waiting to replace a destination path.

```go
type PendingFile struct {
	*os.File
	// contains filtered or unexported fields
}
```

--------------------------------

### func WriteFile

Source: https://pkg.go.dev/github.com/google/renameio/v2

Mirrors os.WriteFile, replacing an existing file with the same name atomically.

```APIDOC
## func WriteFile(filename string, data []byte, perm os.FileMode, opts ...Option) error

### Description
WriteFile mirrors os.WriteFile, replacing an existing file with the same name atomically.

### Parameters
- **filename** (string) - The path to the file.
- **data** ([]byte) - The content to write.
- **perm** (os.FileMode) - The file permissions.
- **opts** (...Option) - Optional configuration for the write operation.
```

--------------------------------

### IgnoreUmask Option

Source: https://pkg.go.dev/github.com/google/renameio/v2

Applies permissions configured via WithPermissions directly, bypassing the umask.

```go
func IgnoreUmask() Option
```

--------------------------------

### func SymlinkRoot

Source: https://pkg.go.dev/github.com/google/renameio/v2

Wraps os.Symlink using a root directory, replacing an existing symlink with the same name atomically.

```APIDOC
## func SymlinkRoot(root *os.Root, oldname, newname string) error

### Description
SymlinkRoot wraps os.Symlink, replacing an existing symlink with the same name atomically.

### Parameters
- **root** (*os.Root) - The root directory context.
- **oldname** (string) - The target of the symlink.
- **newname** (string) - The path of the symlink to create or replace.
```

--------------------------------

### Determine Temporary Directory

Source: https://pkg.go.dev/github.com/google/renameio/v2

Checks if os.TempDir() is suitable for atomic replacements within the destination directory; otherwise, returns the destination directory.

```go
func TempDir(dest string) string
```

--------------------------------

### PendingFile Cleanup Method

Source: https://pkg.go.dev/github.com/google/renameio/v2

Closes and removes the temporary file if CloseAtomicallyReplace has not succeeded.

```go
func (t *PendingFile) Cleanup() error
```

--------------------------------

### func Symlink

Source: https://pkg.go.dev/github.com/google/renameio/v2

Wraps os.Symlink to atomically replace an existing symlink with the same name.

```APIDOC
## func Symlink(oldname, newname string) error

### Description
Symlink wraps os.Symlink, replacing an existing symlink with the same name atomically.

### Parameters
- **oldname** (string) - The target of the symlink.
- **newname** (string) - The path of the symlink to create or replace.
```

--------------------------------

### PendingFile CloseAtomicallyReplace Method

Source: https://pkg.go.dev/github.com/google/renameio/v2

Closes the temporary file and atomically replaces the destination file.

```go
func (t *PendingFile) CloseAtomicallyReplace() error
```

--------------------------------

### WithReplaceOnClose Option

Source: https://pkg.go.dev/github.com/google/renameio/v2

Configures PendingFile.Close() to trigger CloseAtomicallyReplace() automatically.

```go
func WithReplaceOnClose() Option
```

--------------------------------

### PendingFile Close Method

Source: https://pkg.go.dev/github.com/google/renameio/v2

Closes the underlying file, or triggers atomic replacement if configured with WithReplaceOnClose.

```go
func (t *PendingFile) Close() error
```

--------------------------------

### WriteFile function signature

Source: https://pkg.go.dev/github.com/google/renameio/v2/maybe

The function signature for WriteFile, which mirrors os.WriteFile with platform-specific atomic behavior.

```go
func WriteFile(filename string, data []byte, perm os.FileMode) error
```

--------------------------------

### func TempDir

Source: https://pkg.go.dev/github.com/google/renameio/v2

Determines the appropriate temporary directory for atomic file replacement operations.

```APIDOC
## func TempDir(dest string) string

### Description
TempDir checks whether os.TempDir() can be used as a temporary directory for later atomically replacing files within dest. If not, dest is returned.

### Parameters
- **dest** (string) - The destination directory where the file will eventually be placed.
```

--------------------------------

### PendingFile.Cleanup

Source: https://pkg.go.dev/github.com/google/renameio/v2

Cleans up the temporary file if it has not been successfully replaced.

```APIDOC
## func (*PendingFile) Cleanup() error

### Description
Cleanup is a no-op if CloseAtomicallyReplace succeeded, and otherwise closes and removes the temporary file.

### Returns
- **error** - Returns an error if the cleanup operation fails.
```

--------------------------------

### func WriteFile

Source: https://pkg.go.dev/github.com/google/renameio/v2/maybe

Writes data to a file atomically if supported by the platform, otherwise falls back to standard file writing.

```APIDOC
## func WriteFile(filename string, data []byte, perm os.FileMode) error

### Description
WriteFile mirrors os.WriteFile. On Linux it uses renameio.WriteFile to create or replace an existing file with the same name atomically. On Windows, it falls back to os.WriteFile, which does not write the file atomically.

### Parameters
- **filename** (string) - The path to the file to be written.
- **data** ([]byte) - The content to write to the file.
- **perm** (os.FileMode) - The file permissions to apply.

### Returns
- **error** (error) - Returns an error if the write operation fails.
```

--------------------------------

### PendingFile.CloseAtomicallyReplace

Source: https://pkg.go.dev/github.com/google/renameio/v2

Closes the temporary file and atomically replaces the destination file with it.

```APIDOC
## func (*PendingFile) CloseAtomicallyReplace() error

### Description
Closes the temporary file and atomically replaces the destination file with it. A concurrent open(2) call will either open the file previously located at the destination path or the newly written file.

### Returns
- **error** - Returns an error if the operation fails.
```
Tokens:
Raw